Story deck

A sequence of full-frame cards (title, stat, chart, quote, closing) that the reader swipes or steps through. Each card states one fact. It has an optional fixed aspect ratio, a keyboard-accessible pager and a stacked layout for print.

Use when: Use it for a short sequence read on a phone, such as a “year in review”. Each card should be readable in a couple of seconds. State the main fact with its number on the title card. Put one fact on each later card, as a number or as one chart with one highlighted mark under a headline that states the fact. Use five to ten cards. End with a closing card and the sources. Charts in cards should have few data points and direct labels, with no legend.
Avoid when: Findings that need two exhibits in view at once (use executive brief). A single shareable image (use social card). Dense charts or long paragraphs, because a card has little room. One chart that changes step by step (use scrolly chart in steps mode).

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.

Your 2024 on the road

You ran 1,842 km in 2024

That was 23% more than in 2023. You ran 187 times.

Riverside Runners · member report

Card 1 of 7

import { StoryDeck, registerAll } from "insightcharts";

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

export function Example() {
  return (
    <StoryDeck
      aspect="4:5"
      cards={[
        {
          kind: "title",
          tone: "inverse",
          kicker: "Your 2024 on the road",
          title: "You ran 1,842 km in 2024",
          deck: "That was 23% more than in 2023. You ran 187 times.",
          byline: "Riverside Runners · member report",
        },
        {
          kind: "stat",
          kicker: "Distance",
          value: 1842,
          format: "integer",
          label: "Kilometres run in 2024",
          delta: 0.23,
          deltaLabel: "vs 2023",
          context: "An average of 154 km a month",
          text: "You ran in 46 of the year's 52 weeks.",
        },
        {
          kind: "chart",
          kicker: "Month by month",
          title: "October was your highest month at 224 km",
          chart: {
            type: "bar-chart",
            data: [
              { month: "Jan", km: 96 },
              { month: "Feb", km: 104 },
              { month: "Mar", km: 131 },
              { month: "Apr", km: 148 },
              { month: "May", km: 162 },
              { month: "Jun", km: 171 },
              { month: "Jul", km: 120 },
              { month: "Aug", km: 158 },
              { month: "Sep", km: 196 },
              { month: "Oct", km: 224 },
              { month: "Nov", km: 181 },
              { month: "Dec", km: 151 },
            ],
            x: "month",
            y: "km",
            orientation: "vertical",
            sort: "none",
            highlight: "Oct",
            labels: false,
            format: "{value} km",
            height: 240,
          },
          text: "You ran 120 km in July while you were injured. You ran 158 km in August.",
        },
        {
          kind: "chart",
          kicker: "Pace",
          title: "Your easy pace fell from 5.52 to 5.04 minutes per kilometre",
          chart: {
            type: "line-chart",
            data: [
              { month: "Jan", pace: 5.52 },
              { month: "Feb", pace: 5.47 },
              { month: "Mar", pace: 5.41 },
              { month: "Apr", pace: 5.36 },
              { month: "May", pace: 5.33 },
              { month: "Jun", pace: 5.28 },
              { month: "Jul", pace: 5.31 },
              { month: "Aug", pace: 5.24 },
              { month: "Sep", pace: 5.16 },
              { month: "Oct", pace: 5.09 },
              { month: "Nov", pace: 5.07 },
              { month: "Dec", pace: 5.04 },
            ],
            x: "month",
            y: "pace",
            format: "{value} min/km",
            height: 240,
          },
          text: "A lower number is a faster pace. Your pace in August was 5.24.",
        },
        {
          kind: "chart",
          kicker: "Habits",
          tone: "accent",
          title: "41 of your 187 runs started between 6am and 7am",
          chart: {
            type: "radial-bar-chart",
            data: [
              { hour: "00", runs: 0 },
              { hour: "01", runs: 0 },
              { hour: "02", runs: 0 },
              { hour: "03", runs: 0 },
              { hour: "04", runs: 0 },
              { hour: "05", runs: 9 },
              { hour: "06", runs: 41 },
              { hour: "07", runs: 38 },
              { hour: "08", runs: 12 },
              { hour: "09", runs: 4 },
              { hour: "10", runs: 2 },
              { hour: "11", runs: 3 },
              { hour: "12", runs: 8 },
              { hour: "13", runs: 6 },
              { hour: "14", runs: 2 },
              { hour: "15", runs: 1 },
              { hour: "16", runs: 3 },
              { hour: "17", runs: 11 },
              { hour: "18", runs: 22 },
              { hour: "19", runs: 17 },
              { hour: "20", runs: 6 },
              { hour: "21", runs: 2 },
              { hour: "22", runs: 0 },
              { hour: "23", runs: 0 },
            ],
            x: "hour",
            y: "runs",
            labelEvery: 3,
            labels: false,
            height: 260,
          },
          text: "Another 38 started between 7am and 8am. 22 started between 6pm and 7pm.",
        },
        {
          kind: "quote",
          quote: "I started running before work in the spring. I have kept to it since.",
          attribution: "Club member",
          role: "Club newsletter, December 2024",
        },
        {
          kind: "closing",
          kicker: "Next year",
          title: "2,000 km in 2025 needs 167 km a month",
          text: "You averaged 154 km a month in 2024.",
          points: ["You ran 167 km or more in 4 months of 2024.", "July was 51 km below June."],
          action: { label: "Set a 2025 goal", href: "#goal" },
        },
      ]}
      sources="Club activity tracker"
      period="1 January to 31 December 2024"
      note="Illustrative data"
    />
  );
}

{
  "type": "story-deck",
  "aspect": "4:5",
  "cards": [
    {
      "kind": "title",
      "tone": "inverse",
      "kicker": "Your 2024 on the road",
      "title": "You ran 1,842 km in 2024",
      "deck": "That was 23% more than in 2023. You ran 187 times.",
      "byline": "Riverside Runners · member report"
    },
    {
      "kind": "stat",
      "kicker": "Distance",
      "value": 1842,
      "format": "integer",
      "label": "Kilometres run in 2024",
      "delta": 0.23,
      "deltaLabel": "vs 2023",
      "context": "An average of 154 km a month",
      "text": "You ran in 46 of the year's 52 weeks."
    },
    {
      "kind": "chart",
      "kicker": "Month by month",
      "title": "October was your highest month at 224 km",
      "chart": {
        "type": "bar-chart",
        "data": [
          { "month": "Jan", "km": 96 },
          { "month": "Feb", "km": 104 },
          { "month": "Mar", "km": 131 },
          { "month": "Apr", "km": 148 },
          { "month": "May", "km": 162 },
          { "month": "Jun", "km": 171 },
          { "month": "Jul", "km": 120 },
          { "month": "Aug", "km": 158 },
          { "month": "Sep", "km": 196 },
          { "month": "Oct", "km": 224 },
          { "month": "Nov", "km": 181 },
          { "month": "Dec", "km": 151 }
        ],
        "x": "month",
        "y": "km",
        "orientation": "vertical",
        "sort": "none",
        "highlight": "Oct",
        "labels": false,
        "format": "{value} km",
        "height": 240
      },
      "text": "You ran 120 km in July while you were injured. You ran 158 km in August."
    },
    {
      "kind": "chart",
      "kicker": "Pace",
      "title": "Your easy pace fell from 5.52 to 5.04 minutes per kilometre",
      "chart": {
        "type": "line-chart",
        "data": [
          { "month": "Jan", "pace": 5.52 },
          { "month": "Feb", "pace": 5.47 },
          { "month": "Mar", "pace": 5.41 },
          { "month": "Apr", "pace": 5.36 },
          { "month": "May", "pace": 5.33 },
          { "month": "Jun", "pace": 5.28 },
          { "month": "Jul", "pace": 5.31 },
          { "month": "Aug", "pace": 5.24 },
          { "month": "Sep", "pace": 5.16 },
          { "month": "Oct", "pace": 5.09 },
          { "month": "Nov", "pace": 5.07 },
          { "month": "Dec", "pace": 5.04 }
        ],
        "x": "month",
        "y": "pace",
        "format": "{value} min/km",
        "height": 240
      },
      "text": "A lower number is a faster pace. Your pace in August was 5.24."
    },
    {
      "kind": "chart",
      "kicker": "Habits",
      "tone": "accent",
      "title": "41 of your 187 runs started between 6am and 7am",
      "chart": {
        "type": "radial-bar-chart",
        "data": [
          { "hour": "00", "runs": 0 },
          { "hour": "01", "runs": 0 },
          { "hour": "02", "runs": 0 },
          { "hour": "03", "runs": 0 },
          { "hour": "04", "runs": 0 },
          { "hour": "05", "runs": 9 },
          { "hour": "06", "runs": 41 },
          { "hour": "07", "runs": 38 },
          { "hour": "08", "runs": 12 },
          { "hour": "09", "runs": 4 },
          { "hour": "10", "runs": 2 },
          { "hour": "11", "runs": 3 },
          { "hour": "12", "runs": 8 },
          { "hour": "13", "runs": 6 },
          { "hour": "14", "runs": 2 },
          { "hour": "15", "runs": 1 },
          { "hour": "16", "runs": 3 },
          { "hour": "17", "runs": 11 },
          { "hour": "18", "runs": 22 },
          { "hour": "19", "runs": 17 },
          { "hour": "20", "runs": 6 },
          { "hour": "21", "runs": 2 },
          { "hour": "22", "runs": 0 },
          { "hour": "23", "runs": 0 }
        ],
        "x": "hour",
        "y": "runs",
        "labelEvery": 3,
        "labels": false,
        "height": 260
      },
      "text": "Another 38 started between 7am and 8am. 22 started between 6pm and 7pm."
    },
    {
      "kind": "quote",
      "quote": "I started running before work in the spring. I have kept to it since.",
      "attribution": "Club member",
      "role": "Club newsletter, December 2024"
    },
    {
      "kind": "closing",
      "kicker": "Next year",
      "title": "2,000 km in 2025 needs 167 km a month",
      "text": "You averaged 154 km a month in 2024.",
      "points": ["You ran 167 km or more in 4 months of 2024.", "July was 51 km below June."],
      "action": { "label": "Set a 2025 goal", "href": "#goal" }
    }
  ],
  "sources": "Club activity tracker",
  "period": "1 January to 31 December 2024",
  "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 story deck 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.

Big number

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

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.

Pull quote

A large quotation with its attribution.

Radial bar chart

Draws bars around a circle for data that repeats in a cycle, such as hours of the day or months of the year.

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/story-deck

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

Examples

Education: landscape cards

City libraries · 2024 in review

Digital loans were higher than print loans in 2024 for the first time

The five branches had 908,000 visits. That is 91% of the 2019 total.

Card 1 of 5

import { StoryDeck, registerAll } from "insightcharts";

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

export function Example() {
  return (
    <StoryDeck
      aspect="16:9"
      cards={[
        {
          kind: "title",
          kicker: "City libraries · 2024 in review",
          title: "Digital loans were higher than print loans in 2024 for the first time",
          deck: "The five branches had 908,000 visits. That is 91% of the 2019 total.",
        },
        {
          kind: "chart",
          kicker: "Lending",
          title: "Digital loans were 1.33 million in 2024 against 1.24 million for print",
          chart: {
            type: "line-chart",
            data: [
              { year: "2020", Print: 1.42, Digital: 0.61 },
              { year: "2021", Print: 1.18, Digital: 0.83 },
              { year: "2022", Print: 1.31, Digital: 0.92 },
              { year: "2023", Print: 1.29, Digital: 1.08 },
              { year: "2024", Print: 1.24, Digital: 1.33 },
            ],
            x: "year",
            y: ["Digital", "Print"],
            highlight: "Digital",
            format: "{value}m",
            zero: true,
            height: 220,
          },
        },
        {
          kind: "stat",
          kicker: "Visits",
          value: 908000,
          format: "compact",
          label: "Visits to the five branches",
          delta: 0.07,
          deltaLabel: "vs 2023",
          context: "91% of the 2019 total",
        },
        {
          kind: "chart",
          kicker: "Branches",
          title: "Central had 412,000 of the 908,000 visits",
          chart: {
            type: "bar-chart",
            data: [
              { branch: "Central", visits: 412 },
              { branch: "Eastgate", visits: 188 },
              { branch: "Millbrook", visits: 141 },
              { branch: "Harbour", visits: 96 },
              { branch: "Hillside", visits: 71 },
            ],
            x: "branch",
            y: "visits",
            orientation: "horizontal",
            sort: "none",
            highlight: "Central",
            format: "{value}k",
          },
        },
        {
          kind: "closing",
          tone: "inverse",
          title: "Eastgate will open for longer hours in 2025",
          text: "The e-book budget will also increase.",
          action: { label: "Read the annual report", href: "#report" },
        },
      ]}
      sources="City library service annual return"
      note="Illustrative data"
    />
  );
}

{
  "type": "story-deck",
  "aspect": "16:9",
  "cards": [
    {
      "kind": "title",
      "kicker": "City libraries · 2024 in review",
      "title": "Digital loans were higher than print loans in 2024 for the first time",
      "deck": "The five branches had 908,000 visits. That is 91% of the 2019 total."
    },
    {
      "kind": "chart",
      "kicker": "Lending",
      "title": "Digital loans were 1.33 million in 2024 against 1.24 million for print",
      "chart": {
        "type": "line-chart",
        "data": [
          { "year": "2020", "Print": 1.42, "Digital": 0.61 },
          { "year": "2021", "Print": 1.18, "Digital": 0.83 },
          { "year": "2022", "Print": 1.31, "Digital": 0.92 },
          { "year": "2023", "Print": 1.29, "Digital": 1.08 },
          { "year": "2024", "Print": 1.24, "Digital": 1.33 }
        ],
        "x": "year",
        "y": ["Digital", "Print"],
        "highlight": "Digital",
        "format": "{value}m",
        "zero": true,
        "height": 220
      }
    },
    {
      "kind": "stat",
      "kicker": "Visits",
      "value": 908000,
      "format": "compact",
      "label": "Visits to the five branches",
      "delta": 0.07,
      "deltaLabel": "vs 2023",
      "context": "91% of the 2019 total"
    },
    {
      "kind": "chart",
      "kicker": "Branches",
      "title": "Central had 412,000 of the 908,000 visits",
      "chart": {
        "type": "bar-chart",
        "data": [
          { "branch": "Central", "visits": 412 },
          { "branch": "Eastgate", "visits": 188 },
          { "branch": "Millbrook", "visits": 141 },
          { "branch": "Harbour", "visits": 96 },
          { "branch": "Hillside", "visits": 71 }
        ],
        "x": "branch",
        "y": "visits",
        "orientation": "horizontal",
        "sort": "none",
        "highlight": "Central",
        "format": "{value}k"
      }
    },
    {
      "kind": "closing",
      "tone": "inverse",
      "title": "Eastgate will open for longer hours in 2025",
      "text": "The e-book budget will also increase.",
      "action": { "label": "Read the annual report", "href": "#report" }
    }
  ],
  "sources": "City library service annual return",
  "note": "Illustrative data"
}

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

Stacked, auto height

Distance

Kilometres run in 2024

1,842

+23% vs 2023

“I started running before work in the spring.”

Club member

import { StoryDeck } from "insightcharts";

export function Example() {
  return (
    <StoryDeck
      layout="stack"
      aspect="auto"
      cards={[
        {
          kind: "stat",
          kicker: "Distance",
          value: 1842,
          format: "integer",
          label: "Kilometres run in 2024",
          delta: 0.23,
          deltaLabel: "vs 2023",
        },
        {
          kind: "quote",
          quote: "I started running before work in the spring.",
          attribution: "Club member",
        },
      ]}
      note="Illustrative data"
    />
  );
}

{
  "type": "story-deck",
  "layout": "stack",
  "aspect": "auto",
  "cards": [
    {
      "kind": "stat",
      "kicker": "Distance",
      "value": 1842,
      "format": "integer",
      "label": "Kilometres run in 2024",
      "delta": 0.23,
      "deltaLabel": "vs 2023"
    },
    {
      "kind": "quote",
      "quote": "I started running before work in the spring.",
      "attribution": "Club member"
    }
  ],
  "note": "Illustrative data"
}

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

Props

Prop	Type	Default	Description
cardsrequired	Card[]		The cards in order. Each has a `kind`: `title` `{ title, deck?, byline? }`; `stat` `{ value, label, context?, delta?, deltaLabel?, upIsGood?, format?, text? }`; `chart` `{ title, chart, text? }`; `quote` `{ quote, attribution?, role? }`; `closing` `{ title, text?, points?, action?: { label, href } }`. Any card takes `kicker`, `tone: "surface" \| "inverse" \| "accent"` and `id`.
label	string		Accessible name of the deck. Defaults to the first card's title.
aspect	"auto" \| "9:16" \| "4:5" \| "1:1" \| "16:9"	"4:5"	Shape of every card. `auto` lets cards take the height their content needs. `16:9` falls back to `4:5` in containers under 520px.
layout	"pager" \| "stack"	"pager"	`pager` shows one card at a time (swipe, buttons, dots, arrow keys, Home/End). `stack` lists every card in a column.
startAt	number	0	Card shown first (zero-based).
onCardChange	(index: number) => void		Called when the visible card changes.
maxWidth	number		Widest a card is drawn, in px. Default 440 (400 for 9:16, 520 for 1:1, 840 for 16:9). Type and spacing scale with the card.
previousLabel	string	"Previous"	Label of the previous button.
nextLabel	string	"Next"	Label of the next button.
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.
theme	ThemeInput		Theme override, passed on to everything inside.
mode	"auto" \| "system" \| "light" \| "dark"	"auto"	Colour mode, passed on to everything inside.