Comparison brief

A compared with B on one page. It has a headline that states the result, the headline figures mirrored either side of their labels, one hero exhibit that shows both sides, paired exhibits on a shared scale, a verdict callout and a source note.

Use when: Use it for two things a reader has to choose between or compare, such as two countries, two products or a before and an after. Write the result with its number in the headline. Put the four or five most important measures in figures. Use a two-series line, dumbbell, slope or before and after as the hero. In each pair, use the same chart form and the same scale for both sides. The subject side takes the accent colour everywhere and the other side stays grey.
Avoid when: Three or more things (use a comparison table or small multiple grid inside a report page). One thing over time with nothing to compare it with (use timeline story). Paired charts on different scales, because readers compare bar lengths across the pair.

Preview

A template is a whole page, so the preview scrolls inside its frame. Expand it to read it in place, or open it full screen.

Home heating

With the £7,500 grant, a heat pump repays its extra £500 cost in 4 years

After the grant a heat pump costs £3,500 to buy and fit. A gas boiler costs £3,000. The heat pump costs £855 a year to run. The boiler costs £980.

Heat pump

Air source, 7 kW

Measure

Gas boiler

Condensing combi, 30 kW

£3,500

Cost to buy and fit, after grant

£3,000

£855

Running cost per year

£980

0.6

CO2 per year, tonnes

2.3

3.2

Heat out per unit of energy in

0.9

Expected life, years

After 15 years the heat pump has cost £1,375 less than the boiler

Cumulative saving of a heat pump over a gas boiler in pounds, by years since installation. Includes purchase after the £7,500 grant, energy and servicing

Without the grant the heat pump costs £11,000 to buy and fit. That is £8,000 more than the boiler. A saving of £125 a year would take 64 years to repay it.

The January energy bill is £142 for the heat pump and £158 for the boiler

Estimated monthly energy cost for heating and hot water. Both charts use the same scale. The heat pump's bill is lower in all 12 months.

Heat pump

Gas boiler

Cost over 15 years by part

Energy is £12,075 of the heat pump's cost. It is £13,500 of the boiler's.

Heat pump

Gas boiler

Verdict

Choose the heat pump if you get the grant and will stay at least 5 years

Without the grant the boiler is cheaper. The figures assume electricity and gas prices stay at their Q4 2024 levels.

import { ComparisonBrief, registerAll } from "insightcharts";

// The slot props below are JSON specs. This makes their `type` names resolvable.
registerAll();

export function Example() {
  return (
    <ComparisonBrief
      kicker="Home heating"
      title="With the £7,500 grant, a heat pump repays its extra £500 cost in 4 years"
      deck="After the grant a heat pump costs £3,500 to buy and fit. A gas boiler costs £3,000. The heat pump costs £855 a year to run. The boiler costs £980."
      a={{ name: "Heat pump", detail: "Air source, 7 kW" }}
      b={{ name: "Gas boiler", detail: "Condensing combi, 30 kW" }}
      figures={[
        {
          label: "Cost to buy and fit, after grant",
          a: 3500,
          b: 3000,
          format: { style: "currency", currency: "GBP", maximumFractionDigits: 0 },
          better: "lower",
        },
        {
          label: "Running cost per year",
          a: 855,
          b: 980,
          format: "currency:GBP",
          better: "lower",
        },
        {
          label: "CO2 per year, tonnes",
          a: 0.6,
          b: 2.3,
          format: "decimal:1",
          better: "lower",
        },
        {
          label: "Heat out per unit of energy in",
          a: 3.2,
          b: 0.9,
          format: "decimal:1",
          better: "higher",
        },
        { label: "Expected life, years", a: 20, b: 15, better: "higher" },
      ]}
      hero={{
        type: "line-chart",
        data: [
          { year: "0", saving: -500 },
          { year: "1", saving: -375 },
          { year: "2", saving: -250 },
          { year: "3", saving: -125 },
          { year: "4", saving: 0 },
          { year: "5", saving: 125 },
          { year: "6", saving: 250 },
          { year: "7", saving: 375 },
          { year: "8", saving: 500 },
          { year: "9", saving: 625 },
          { year: "10", saving: 750 },
          { year: "11", saving: 875 },
          { year: "12", saving: 1000 },
          { year: "13", saving: 1125 },
          { year: "14", saving: 1250 },
          { year: "15", saving: 1375 },
        ],
        x: "year",
        y: "saving",
        format: {
          style: "currency",
          currency: "GBP",
          maximumFractionDigits: 0,
          signDisplay: "exceptZero",
        },
        area: true,
        title: "After 15 years the heat pump has cost £1,375 less than the boiler",
        subtitle: "Cumulative saving of a heat pump over a gas boiler in pounds, by years since installation. Includes purchase after the £7,500 grant, energy and servicing",
        annotations: [
          {
            type: "line",
            axis: "y",
            value: 0,
            label: "Same cost as the boiler",
            dashed: false,
            emphasis: true,
          },
          { type: "point", x: "4", y: 0, label: "Break-even", position: "top" },
        ],
      }}
      heroText="Without the grant the heat pump costs £11,000 to buy and fit. That is £8,000 more than the boiler. A saving of £125 a year would take 64 years to repay it."
      pairs={[
        {
          title: "The January energy bill is £142 for the heat pump and £158 for the boiler",
          text: "Estimated monthly energy cost for heating and hot water. Both charts use the same scale. The heat pump's bill is lower in all 12 months.",
          a: {
            type: "bar-chart",
            data: [
              { month: "Jan", cost: 142 },
              { month: "Feb", cost: 128 },
              { month: "Mar", cost: 102 },
              { month: "Apr", cost: 68 },
              { month: "May", cost: 40 },
              { month: "Jun", cost: 28 },
              { month: "Jul", cost: 25 },
              { month: "Aug", cost: 26 },
              { month: "Sep", cost: 38 },
              { month: "Oct", cost: 66 },
              { month: "Nov", cost: 98 },
              { month: "Dec", cost: 134 },
            ],
            x: "month",
            y: "cost",
            orientation: "vertical",
            sort: "none",
            labels: false,
            format: "currency:GBP",
            height: 200,
            option: { yAxis: { max: 160 } },
          },
          b: {
            type: "bar-chart",
            data: [
              { month: "Jan", cost: 158 },
              { month: "Feb", cost: 141 },
              { month: "Mar", cost: 115 },
              { month: "Apr", cost: 78 },
              { month: "May", cost: 49 },
              { month: "Jun", cost: 37 },
              { month: "Jul", cost: 34 },
              { month: "Aug", cost: 35 },
              { month: "Sep", cost: 46 },
              { month: "Oct", cost: 74 },
              { month: "Nov", cost: 107 },
              { month: "Dec", cost: 146 },
            ],
            x: "month",
            y: "cost",
            orientation: "vertical",
            sort: "none",
            labels: false,
            format: "currency:GBP",
            height: 200,
            highlight: "none",
            option: { yAxis: { max: 160 } },
          },
        },
        {
          title: "Cost over 15 years by part",
          text: "Energy is £12,075 of the heat pump's cost. It is £13,500 of the boiler's.",
          a: {
            type: "segmented-bar",
            data: [
              { part: "Purchase and fitting", gbp: 3500 },
              { part: "Energy", gbp: 12075 },
              { part: "Servicing", gbp: 1500 },
            ],
            name: "part",
            value: "gbp",
            format: "currency:GBP",
          },
          b: {
            type: "segmented-bar",
            data: [
              { part: "Purchase and fitting", gbp: 3000 },
              { part: "Energy", gbp: 13500 },
              { part: "Servicing", gbp: 1200 },
            ],
            name: "part",
            value: "gbp",
            format: "currency:GBP",
          },
        },
      ]}
      verdict={{
        lead: "Choose the heat pump if you get the grant and will stay at least 5 years",
        body: "Without the grant the boiler is cheaper. The figures assume electricity and gas prices stay at their Q4 2024 levels.",
      }}
      sources={[
        "Energy regulator price cap, Q4 2024",
        "Installer quotes collected by the author",
      ]}
      method="A house using 11,500 kWh of heat a year. Heat pump seasonal efficiency is 3.2. Boiler efficiency is 90%. Prices held flat in real terms."
      note="Illustrative data"
    />
  );
}

{
  "type": "comparison-brief",
  "kicker": "Home heating",
  "title": "With the £7,500 grant, a heat pump repays its extra £500 cost in 4 years",
  "deck": "After the grant a heat pump costs £3,500 to buy and fit. A gas boiler costs £3,000. The heat pump costs £855 a year to run. The boiler costs £980.",
  "a": { "name": "Heat pump", "detail": "Air source, 7 kW" },
  "b": { "name": "Gas boiler", "detail": "Condensing combi, 30 kW" },
  "figures": [
    {
      "label": "Cost to buy and fit, after grant",
      "a": 3500,
      "b": 3000,
      "format": { "style": "currency", "currency": "GBP", "maximumFractionDigits": 0 },
      "better": "lower"
    },
    {
      "label": "Running cost per year",
      "a": 855,
      "b": 980,
      "format": "currency:GBP",
      "better": "lower"
    },
    {
      "label": "CO2 per year, tonnes",
      "a": 0.6,
      "b": 2.3,
      "format": "decimal:1",
      "better": "lower"
    },
    {
      "label": "Heat out per unit of energy in",
      "a": 3.2,
      "b": 0.9,
      "format": "decimal:1",
      "better": "higher"
    },
    { "label": "Expected life, years", "a": 20, "b": 15, "better": "higher" }
  ],
  "hero": {
    "type": "line-chart",
    "data": [
      { "year": "0", "saving": -500 },
      { "year": "1", "saving": -375 },
      { "year": "2", "saving": -250 },
      { "year": "3", "saving": -125 },
      { "year": "4", "saving": 0 },
      { "year": "5", "saving": 125 },
      { "year": "6", "saving": 250 },
      { "year": "7", "saving": 375 },
      { "year": "8", "saving": 500 },
      { "year": "9", "saving": 625 },
      { "year": "10", "saving": 750 },
      { "year": "11", "saving": 875 },
      { "year": "12", "saving": 1000 },
      { "year": "13", "saving": 1125 },
      { "year": "14", "saving": 1250 },
      { "year": "15", "saving": 1375 }
    ],
    "x": "year",
    "y": "saving",
    "format": {
      "style": "currency",
      "currency": "GBP",
      "maximumFractionDigits": 0,
      "signDisplay": "exceptZero"
    },
    "area": true,
    "title": "After 15 years the heat pump has cost £1,375 less than the boiler",
    "subtitle": "Cumulative saving of a heat pump over a gas boiler in pounds, by years since installation. Includes purchase after the £7,500 grant, energy and servicing",
    "annotations": [
      {
        "type": "line",
        "axis": "y",
        "value": 0,
        "label": "Same cost as the boiler",
        "dashed": false,
        "emphasis": true
      },
      { "type": "point", "x": "4", "y": 0, "label": "Break-even", "position": "top" }
    ]
  },
  "heroText": "Without the grant the heat pump costs £11,000 to buy and fit. That is £8,000 more than the boiler. A saving of £125 a year would take 64 years to repay it.",
  "pairs": [
    {
      "title": "The January energy bill is £142 for the heat pump and £158 for the boiler",
      "text": "Estimated monthly energy cost for heating and hot water. Both charts use the same scale. The heat pump's bill is lower in all 12 months.",
      "a": {
        "type": "bar-chart",
        "data": [
          { "month": "Jan", "cost": 142 },
          { "month": "Feb", "cost": 128 },
          { "month": "Mar", "cost": 102 },
          { "month": "Apr", "cost": 68 },
          { "month": "May", "cost": 40 },
          { "month": "Jun", "cost": 28 },
          { "month": "Jul", "cost": 25 },
          { "month": "Aug", "cost": 26 },
          { "month": "Sep", "cost": 38 },
          { "month": "Oct", "cost": 66 },
          { "month": "Nov", "cost": 98 },
          { "month": "Dec", "cost": 134 }
        ],
        "x": "month",
        "y": "cost",
        "orientation": "vertical",
        "sort": "none",
        "labels": false,
        "format": "currency:GBP",
        "height": 200,
        "option": { "yAxis": { "max": 160 } }
      },
      "b": {
        "type": "bar-chart",
        "data": [
          { "month": "Jan", "cost": 158 },
          { "month": "Feb", "cost": 141 },
          { "month": "Mar", "cost": 115 },
          { "month": "Apr", "cost": 78 },
          { "month": "May", "cost": 49 },
          { "month": "Jun", "cost": 37 },
          { "month": "Jul", "cost": 34 },
          { "month": "Aug", "cost": 35 },
          { "month": "Sep", "cost": 46 },
          { "month": "Oct", "cost": 74 },
          { "month": "Nov", "cost": 107 },
          { "month": "Dec", "cost": 146 }
        ],
        "x": "month",
        "y": "cost",
        "orientation": "vertical",
        "sort": "none",
        "labels": false,
        "format": "currency:GBP",
        "height": 200,
        "highlight": "none",
        "option": { "yAxis": { "max": 160 } }
      }
    },
    {
      "title": "Cost over 15 years by part",
      "text": "Energy is £12,075 of the heat pump's cost. It is £13,500 of the boiler's.",
      "a": {
        "type": "segmented-bar",
        "data": [
          { "part": "Purchase and fitting", "gbp": 3500 },
          { "part": "Energy", "gbp": 12075 },
          { "part": "Servicing", "gbp": 1500 }
        ],
        "name": "part",
        "value": "gbp",
        "format": "currency:GBP"
      },
      "b": {
        "type": "segmented-bar",
        "data": [
          { "part": "Purchase and fitting", "gbp": 3000 },
          { "part": "Energy", "gbp": 13500 },
          { "part": "Servicing", "gbp": 1200 }
        ],
        "name": "part",
        "value": "gbp",
        "format": "currency:GBP"
      }
    }
  ],
  "verdict": {
    "lead": "Choose the heat pump if you get the grant and will stay at least 5 years",
    "body": "Without the grant the boiler is cheaper. The figures assume electricity and gas prices stay at their Q4 2024 levels."
  },
  "sources": ["Energy regulator price cap, Q4 2024", "Installer quotes collected by the author"],
  "method": "A house using 11,500 kWh of heat a year. Heat pump seasonal efficiency is 3.2. Boiler efficiency is 90%. Prices held flat in real terms.",
  "note": "Illustrative data"
}

Render with import { Insight } from "insightcharts" and <Insight spec={spec} />. Nested specs resolve by name; nothing else to import.

Composition

Built from

The comparison brief template is assembled from 7 atoms. Any slot also takes any other component.

Atoms

Bar chart

Compares a value across categories with bars from a zero baseline.

Callout

A boxed statement of fact with a short bold lead and a sentence of explanation. The tone is marked by icon and tint.

Headline

The opening block of a piece or section: kicker, title, one-sentence deck and a byline/date line.

Line chart

Shows how one or more values change over time or another ordered dimension.

Prose

A readable block of narration at a 45-75 character measure, for the text between charts.

Segmented bar

Splits one whole into proportional segments along a single horizontal bar.

Source note

A sourcing footer for a whole piece: sources with optional links, the period covered, method, caveats and credit.

Installation

$ pnpm dlx shadcn@latest add @insightcharts/comparison-brief

The CLI copies the source into your project and needs the @insightcharts registry in components.json; see installation. With the package, import it by name:

import { ComparisonBrief } from "insightcharts";

Examples

Transport: a stacked hero, no pairs

London to Edinburgh

Flying from London to Edinburgh is 35 minutes faster than the train, door to door

The plane takes 275 minutes and the train 310. The flight itself lasts 80 minutes. The plane emits 140 kg of CO2 per passenger. The train emits 13 kg.

Train

Measure

Plane

310

Door to door, minutes

275

CO2 per passenger, kg

140

£78

Typical fare booked two weeks ahead

£92

240

Minutes you can spend working

80 of the plane's 275 minutes are spent in the air

Minutes per stage, city centre to city centre

Source: Timetables and airport guidance, weekday morning departures

Verdict

Take the train unless you need the 35 minutes

The train fare is £78 and the plane fare is £92. The train gives 240 minutes of working time. The plane gives 50.

import { ComparisonBrief, registerAll } from "insightcharts";

// The slot props below are JSON specs. This makes their `type` names resolvable.
registerAll();

export function Example() {
  return (
    <ComparisonBrief
      kicker="London to Edinburgh"
      title="Flying from London to Edinburgh is 35 minutes faster than the train, door to door"
      deck="The plane takes 275 minutes and the train 310. The flight itself lasts 80 minutes. The plane emits 140 kg of CO2 per passenger. The train emits 13 kg."
      a="Train"
      b="Plane"
      figures={[
        { label: "Door to door, minutes", a: 310, b: 275, better: "lower" },
        { label: "CO2 per passenger, kg", a: 13, b: 140, better: "lower" },
        {
          label: "Typical fare booked two weeks ahead",
          a: 78,
          b: 92,
          format: "currency:GBP",
          better: "lower",
        },
        { label: "Minutes you can spend working", a: 240, b: 50, better: "higher" },
      ]}
      hero={{
        type: "bar-chart",
        data: [
          {
            mode: "Train",
            "Getting there": 25,
            "Waiting and boarding": 15,
            "In transit": 260,
            Onward: 10,
          },
          {
            mode: "Plane",
            "Getting there": 55,
            "Waiting and boarding": 95,
            "In transit": 80,
            Onward: 45,
          },
        ],
        x: "mode",
        y: ["Getting there", "Waiting and boarding", "In transit", "Onward"],
        stack: true,
        orientation: "horizontal",
        sort: "none",
        format: "{value} min",
        title: "80 of the plane's 275 minutes are spent in the air",
        subtitle: "Minutes per stage, city centre to city centre",
        source: "Timetables and airport guidance, weekday morning departures",
      }}
      verdict={{
        lead: "Take the train unless you need the 35 minutes",
        body: "The train fare is £78 and the plane fare is £92. The train gives 240 minutes of working time. The plane gives 50.",
        tone: "positive",
      }}
      sources={["Operator timetables", "Government greenhouse gas conversion factors"]}
      note="Illustrative fares and times"
    />
  );
}

{
  "type": "comparison-brief",
  "kicker": "London to Edinburgh",
  "title": "Flying from London to Edinburgh is 35 minutes faster than the train, door to door",
  "deck": "The plane takes 275 minutes and the train 310. The flight itself lasts 80 minutes. The plane emits 140 kg of CO2 per passenger. The train emits 13 kg.",
  "a": "Train",
  "b": "Plane",
  "figures": [
    { "label": "Door to door, minutes", "a": 310, "b": 275, "better": "lower" },
    { "label": "CO2 per passenger, kg", "a": 13, "b": 140, "better": "lower" },
    {
      "label": "Typical fare booked two weeks ahead",
      "a": 78,
      "b": 92,
      "format": "currency:GBP",
      "better": "lower"
    },
    { "label": "Minutes you can spend working", "a": 240, "b": 50, "better": "higher" }
  ],
  "hero": {
    "type": "bar-chart",
    "data": [
      {
        "mode": "Train",
        "Getting there": 25,
        "Waiting and boarding": 15,
        "In transit": 260,
        "Onward": 10
      },
      {
        "mode": "Plane",
        "Getting there": 55,
        "Waiting and boarding": 95,
        "In transit": 80,
        "Onward": 45
      }
    ],
    "x": "mode",
    "y": ["Getting there", "Waiting and boarding", "In transit", "Onward"],
    "stack": true,
    "orientation": "horizontal",
    "sort": "none",
    "format": "{value} min",
    "title": "80 of the plane's 275 minutes are spent in the air",
    "subtitle": "Minutes per stage, city centre to city centre",
    "source": "Timetables and airport guidance, weekday morning departures"
  },
  "verdict": {
    "lead": "Take the train unless you need the 35 minutes",
    "body": "The train fare is £78 and the plane fare is £92. The train gives 240 minutes of working time. The plane gives 50.",
    "tone": "positive"
  },
  "sources": ["Operator timetables", "Government greenhouse gas conversion factors"],
  "note": "Illustrative fares and times"
}

Render with import { Insight } from "insightcharts" and <Insight spec={spec} />. Nested specs resolve by name; nothing else to import.

Props

Prop	Type	Default	Description
titlerequired	string		The result of the comparison, as one plain sentence with the number in it.
kicker	string		Small label above the title.
deck	string		One-sentence standfirst.
byline	string		Author line.
date	string		Publication date.
arequired	string \| { name, detail? }		Side A, shown on the left.
brequired	string \| { name, detail? }		Side B, shown on the right.
subject	"a" \| "b" \| "none"	"a"	The side the piece is about. It takes the accent colour; the other stays grey. Match it with `highlight` in the charts.
figures	{ label, a, b, format?, better?: "higher" \| "lower" }[]		Headline measures. Numeric values get mirrored bars scaled within each row; `better` sets the stronger value bolder.
hero	Slot		The exhibit that shows both sides at once. Default height 360px.
heroText	string		One or two sentences under the hero.
pairs	{ title, text?, a: Slot, b: Slot }[]		Paired exhibits under one heading. A is on the left and B on the right; they stack in narrow containers. Use the same form and scale for both.
verdict	{ lead?, body?, label?, tone? }		The closing recommendation, shown as a callout.
sources	string \| { name, url? } \| (string \| { name, url? })[]		Where the data comes from, shown in the closing source note. Entries with a `url` are linked.
period	string		The period the data covers.
method	string		How the numbers were produced: definitions, adjustments, exclusions.
note	string		Caveats the reader should know, e.g. "Illustrative data".
credit	string		Who made the piece.
level	1 \| 2 \| 3 \| 4 \| 5 \| 6	1	Heading level of the title; section headings follow one level down.
maxWidth	number \| string		Widest the piece may get. It is centred in wider containers.
theme	ThemeInput		Theme override, passed on to everything inside.
mode	"auto" \| "system" \| "light" \| "dark"	"auto"	Colour mode, passed on to everything inside.