Hero figure

The opening exhibit of a piece: kicker, headline and deck above one large chart, with a source line underneath.

Use when: At the very top of a data story or a one-page report. The headline states the main fact with its number. The chart shows that fact.
Avoid when: Giving the chart its own title (the headline is the title; use the chart's subtitle for the measure). A second hero on the same page: later sections use section or chart with callout.

Preview

Energy transition

Solar supplied 11.1% of EU electricity in 2024

Coal's share fell from 24.6% in 2015 to 9.8% in 2024.

By Ana RuizJanuary 23, 2025

Solar and coal share of EU electricity generation, 2015 to 2024

import { HeroFigure, registerAll } from "insightcharts";

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

export function Example() {
  return (
    <HeroFigure
      kicker="Energy transition"
      title="Solar supplied 11.1% of EU electricity in 2024"
      deck="Coal's share fell from 24.6% in 2015 to 9.8% in 2024."
      byline="By Ana Ruiz"
      date="2025-01-23"
      chart={{
        type: "line-chart",
        data: [
          { year: "2015", Solar: 2.9, Coal: 24.6 },
          { year: "2016", Solar: 3, Coal: 22 },
          { year: "2017", Solar: 3.4, Coal: 20.6 },
          { year: "2018", Solar: 3.7, Coal: 19.2 },
          { year: "2019", Solar: 4.2, Coal: 15 },
          { year: "2020", Solar: 5, Coal: 13 },
          { year: "2021", Solar: 5.4, Coal: 14.7 },
          { year: "2022", Solar: 7, Coal: 15.8 },
          { year: "2023", Solar: 9.1, Coal: 12.3 },
          { year: "2024", Solar: 11.1, Coal: 9.8 },
        ],
        x: "year",
        y: ["Solar", "Coal"],
        format: "{value}%",
        zero: true,
        height: 380,
        subtitle: "Solar and coal share of EU electricity generation, 2015 to 2024",
        annotations: [
          { type: "point", x: "2024", y: 11.1, label: "Solar 11.1%", position: "left" },
        ],
      }}
      source={{
        name: "Ember, European Electricity Review 2025",
        url: "https://ember-energy.org",
      }}
      note="Figures are approximate, for illustration"
      period="2015 to 2024"
    />
  );
}

{
  "type": "hero-figure",
  "kicker": "Energy transition",
  "title": "Solar supplied 11.1% of EU electricity in 2024",
  "deck": "Coal's share fell from 24.6% in 2015 to 9.8% in 2024.",
  "byline": "By Ana Ruiz",
  "date": "2025-01-23",
  "chart": {
    "type": "line-chart",
    "data": [
      { "year": "2015", "Solar": 2.9, "Coal": 24.6 },
      { "year": "2016", "Solar": 3, "Coal": 22 },
      { "year": "2017", "Solar": 3.4, "Coal": 20.6 },
      { "year": "2018", "Solar": 3.7, "Coal": 19.2 },
      { "year": "2019", "Solar": 4.2, "Coal": 15 },
      { "year": "2020", "Solar": 5, "Coal": 13 },
      { "year": "2021", "Solar": 5.4, "Coal": 14.7 },
      { "year": "2022", "Solar": 7, "Coal": 15.8 },
      { "year": "2023", "Solar": 9.1, "Coal": 12.3 },
      { "year": "2024", "Solar": 11.1, "Coal": 9.8 }
    ],
    "x": "year",
    "y": ["Solar", "Coal"],
    "format": "{value}%",
    "zero": true,
    "height": 380,
    "subtitle": "Solar and coal share of EU electricity generation, 2015 to 2024",
    "annotations": [
      {
        "type": "point",
        "x": "2024",
        "y": 11.1,
        "label": "Solar 11.1%",
        "position": "left"
      }
    ]
  },
  "source": {
    "name": "Ember, European Electricity Review 2025",
    "url": "https://ember-energy.org"
  },
  "note": "Figures are approximate, for illustration",
  "period": "2015 to 2024"
}

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

Composition

Built from

The pieces hero figure renders or expects in its slots.

Atoms

Big number

A featured statistic with its label, change and the context that gives it meaning.

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.

Source note

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

Used in

No template lists hero figure in its composes. It still fits any slot that takes a component.

Installation

$ pnpm dlx shadcn@latest add @insightcharts/hero-figure

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 { HeroFigure } from "insightcharts";

Examples

Centered, big number as the exhibit

33% of the world's population had never used the internet in 2023

The ITU estimates that 2.6 billion people were offline.

People who have never used the internet

2.6 billion

33% of the world's population in 2023

import { HeroFigure, registerAll } from "insightcharts";

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

export function Example() {
  return (
    <HeroFigure
      align="center"
      title="33% of the world's population had never used the internet in 2023"
      deck="The ITU estimates that 2.6 billion people were offline."
      chart={{
        type: "big-number",
        size: "hero",
        align: "center",
        value: "2.6 billion",
        label: "People who have never used the internet",
        context: "33% of the world's population in 2023",
      }}
      source="ITU Facts and Figures 2023"
      note="Figures are approximate, for illustration"
    />
  );
}

{
  "type": "hero-figure",
  "align": "center",
  "title": "33% of the world's population had never used the internet in 2023",
  "deck": "The ITU estimates that 2.6 billion people were offline.",
  "chart": {
    "type": "big-number",
    "size": "hero",
    "align": "center",
    "value": "2.6 billion",
    "label": "People who have never used the internet",
    "context": "33% of the world's population in 2023"
  },
  "source": "ITU Facts and Figures 2023",
  "note": "Figures are approximate, for illustration"
}

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 main fact, as one plain sentence with its number.
kicker	string		Small label above the title: the series or topic.
deck	string		One plain sentence under the title that adds a second fact.
byline	string		Author line, e.g. "By Ana Ruiz".
date	string		Publication date. ISO dates are formatted for the locale.
chartrequired	Slot		The hero chart: a spec or a React element, without its own title.
source	string \| { name, url? } \| (string \| { name, url? })[]		Where the data comes from. Entries with a `url` are linked.
period	string		The period the data covers.
note	string		Caveats the reader should know.
align	"left" \| "center"	"left"	Headline alignment.
level	1 \| 2 \| 3 \| 4 \| 5 \| 6	1	Heading level of the title.
children	ReactNode		JSX alternative to `chart`.
theme	ThemeInput		Theme override, passed on to the headline, chart and source note.
mode	"auto" \| "system" \| "light" \| "dark"	"auto"	Colour mode.