Quickstart

A first chart#

Pass rows, name the fields to draw, and write a title that states one fact from the data with its number.

import { BarChart } from "insightcharts";

const data = [
  { country: "Norway", share: 98 },
  { country: "Brazil", share: 89 },
  { country: "Canada", share: 68 },
  { country: "Germany", share: 52 },
  { country: "United States", share: 23 },
];

export function Example() {
  return (
    <BarChart
      data={data}
      x="country"
      y="share"
      format={"{value}%"}
      highlight="Norway"
      title="Renewables supplied 98% of Norway's electricity in 2023"
      subtitle="Share of electricity generation from renewables, 2023"
      note="Illustrative figures"
      height={260}
    />
  );
}

{
  "type": "bar-chart",
  "data": [
    { "country": "Norway", "share": 98 },
    { "country": "Brazil", "share": 89 },
    { "country": "Canada", "share": 68 },
    { "country": "Germany", "share": 52 },
    { "country": "United States", "share": 23 }
  ],
  "x": "country",
  "y": "share",
  "format": "{value}%",
  "highlight": "Norway",
  "title": "Renewables supplied 98% of Norway's electricity in 2023",
  "subtitle": "Share of electricity generation from renewables, 2023",
  "note": "Illustrative figures",
  "height": 260
}

The props every chart takes#

Every chart built on the engine takes the same four groups of props.

1. Data: data is rows, CSV text, a URL or a function (see data). transform reshapes it first.
2. Fields: x, y, series and so on are field names, as strings. There are no accessor functions, so a chart can be written as JSON.
3. Text: title is one plain statement of what the data shows, with the number and the period. subtitle names the measure, unit, population and period. source and note are shown under the chart. See writing titles.
4. Emphasis: highlight names the entity the title is about, and the other series are drawn in grey. annotations mark a date, a threshold or a single value.

The chart draws its own title, legend, source line, loading skeleton, error message and empty state. It fills the width of its container. height defaults to 360 pixels, except on charts that declare a natural height (row-based charts such as a horizontal bar chart grow with their rows); pass height to fix it, or aspect (width divided by height).

The full list of shared props is in the collapsible "Common chart props" table on any chart page, for example bar chart.

Formatting numbers#

format controls how values print on labels, axes and tooltips. It accepts a shorthand string, a template, Intl.NumberFormat options, or a function.

Big numbers#

Use BigNumber to show a single statistic. It takes a label, a change and a line of context, such as an earlier value.

import { BigNumber } from "insightcharts";

export function Example() {
  return (
    <BigNumber
      value={0.317}
      format="percent"
      label="Share of global electricity from renewables"
      delta={0.021}
      deltaLabel="vs 2023"
      context="Up from 19% in 2010"
      size="hero"
    />
  );
}

{
  "type": "big-number",
  "value": 0.317,
  "format": "percent",
  "label": "Share of global electricity from renewables",
  "delta": 0.021,
  "deltaLabel": "vs 2023",
  "context": "Up from 19% in 2010",
  "size": "hero"
}

Setting defaults with a provider#

Charts work with no provider. InsightProvider sets defaults for everything beneath it, and providers nest, so one section of a page can carry its own theme or mode.

import { InsightProvider } from "insightcharts";

<InsightProvider theme={{ accent: "#7c3aed" }} locale="en-GB" exportable>
  {children}
</InsightProvider>

Next steps#

• Data: every accepted shape and every transform.
• Highlighting and annotations: highlight, annotations and the rules for writing titles.
• The JSON spec: the same components written as JSON.
• Templates: page layouts that take their content as props.