Walk-through

This is an in-depth tutorial that demonstrates some of Graphique’s core functionality. We’ll walk through the process of creating a useful, interactive graphic that gradually builds in complexity. By going through it, you should get a sense for how Graphique:

maps data properties to visual properties using Aesthetics and scales
includes helpful pieces for interpreting visualized data (labels, legends, tooltips, and more)
is configurable — easily adjust/replace defaults (scales, tooltips, themes, etc.)
can be integrated with React’s state management to create stateful visualizations

First we’ll install the necessary dependencies for our example.

npm i @graphique/graphique @graphique/geom-point @graphique/datasets d3-scale

pnpm add @graphique/graphique @graphique/geom-point @graphique/datasets d3-scale

yarn add @graphique/graphique @graphique/geom-point @graphique/datasets d3-scale

bun add @graphique/graphique @graphique/geom-point @graphique/datasets d3-scale

Show me the data

We’ll be using Graphique’s gapminder dataset that contains various information on countries over time. It’s an array of objects that looks like this:

gapminder.json

[
  {
    "country": "Afghanistan",
    "continent": "Asia",
    "year": 1952,
    "lifeExp": 28.801,
    "pop": 8425333,
    "gdpPercap": 779.4453,
  },
  ...
  {
    "country": "Zimbabwe",
    "continent": "Africa",
    "year": 2007,
    "lifeExp": 43.487,
    "pop": 12311143,
    "gdpPercap": 469.7093,
  },
]

A layered approach

For this example, we’re interested in the relationship between GDP and life expectancy — the wealth (and health) of nations. We also would like to incorporate each country’s population and continent, as well as the measurement year. We’ll start with the basics and build our way up to a useful, interactive graphic.

The base

To begin, we’ll look at only the most recent year’s data (2007). This is what you get for free when plugging in your data and mapping a coordinate system (x, y Aesthetics):

GapMinder.tsx

import { GG } from '@graphique/graphique';
import { gapminder } from '@graphique/datasets';
 
const data = gapminder.filter(d => d.year === 2007);
 
export const GapMinderChart = () => {
  return (
    <GG
      data={data}
      aes={{
        x: (d) => d.gdpPercap,
        y: (d) => d.lifeExp
      }}
      isContainerWidth
    />
  );
};

Using the defaults, our (empty) graphic gets:

a coordinate system with a grid
scaled axes with ticks and tick labels
and dimensions (its parent container's width × 450px)

This is a good start but isn’t very useful without including any Geometries (Geoms).

Draw the countries

Let’s draw these countries in the form of a scatterplot. We can turn what we have into a scatterplot simply by including GeomPoint as a child.

GapMinder.tsx

import { GG } from '@graphique/graphique';
import { GeomPoint } from '@graphique/geom-point';
import { gapminder } from '@graphique/datasets';
 
const data = gapminder.filter(d => d.year === 2007);
 
export const GapMinderChart = () => {
  return (
    <GG
      data={data}
      aes={{
        x: (d) => d.gdpPercap,
        y: (d) => d.lifeExp
      }}
      isContainerWidth
    >
      <GeomPoint />
    </GG>
  );
};

Data visualized! Each object in our data array gets a point positioned according to what’s returned from the x and y accessor methods in aes. You might also notice we now have a (very basic) tooltip shown when hovering near each point.

This is good for only a few lines of code, but still pretty crude. We’ll add some polish to our graphic next.

Starting to customize

We’ll add some readable labels and change the look of the points to tighten this up a little.

GapMinder.tsx

import { GG, Labels } from '@graphique/graphique';
import { GeomPoint } from '@graphique/geom-point';
import { gapminder } from '@graphique/datasets';
import styles from './gapMinder.module.css';
 
const data = gapminder.filter(d => d.year === 2007);
 
export const GapMinderChart = () => {
  return (
    <GG
      data={data}
      aes={{
        x: (d) => d.gdpPercap,
        y: (d) => d.lifeExp,
        label: (d) => d.country,
      }}
      isContainerWidth
    >
      <GeomPoint
        attr={{
          opacity: 0.7,
          fill: '#298670',
          r: 3,
        }}
      />
      <Labels
        x='GDP per capita'
        y='Life expectancy (years)'
        header={
          <span className={styles.title}>The health and wealth of nations</span>
        }
      />
    </GG>
  );
};

We’re on our way to something useful now — our axes are labeled and and we put a title in our header.

Notice our tooltip has the x and y values labeled now (based on our axis labels), and by mapping the label Aesthetic to each country, we can also see which country is which.

Use and format log x scale

Since it is so skewed in this dataset, it makes sense to visualize GDP along a log scale instead of the linear one Graphique created for us by default. Rather than transforming these values ourselves, we can pass scaleLog from d3-scale into Graphique’s ScaleX to modify its behavior.

We’ll also format GDP shown in the tooltip and the x tick labels in terms of inflation-adjusted dollars. In addition, we can determine the number of x ticks to show based on the container width — this way, the x axis won’t be cluttered in narrow charting conditions (e.g. on phones).

We’ll define some utility formatting functions in a separate file to import and use in our visualization.

GapMinder.tsx

import { GG, Labels, ScaleX, Tooltip } from '@graphique/graphique';
import { GeomPoint } from '@graphique/geom-point';
import { gapminder } from '@graphique/datasets';
import { scaleLog } from 'd3-scale';
import { formatGDP, formatXTick, getNumXTicks } from './formattingUtils';
import styles from './gapMinder.module.css';
 
const data = gapminder.filter(d => d.year === 2007);
 
export const GapMinderChart = () => {
  return (
    <GG
      data={data}
      aes={{
        x: (d) => d.gdpPercap,
        y: (d) => d.lifeExp,
        label: (d) => d.country,
      }}
      isContainerWidth
    >
      <GeomPoint
        attr={{
          opacity: 0.7
          fill: '#298670',
          r: 3,
        }}
      />
      <ScaleX
        type={scaleLog}
        format={formatXTick}
        numTicks={getNumXTicks}
      />
      <Tooltip xFormat={formatGDP} />
      <Labels
        x='GDP per capita'
        y='Life expectancy (years)'
        header={
          <span className={styles.title}>The health and wealth of nations</span>
        }
      />
    </GG>
  );
};

formattingUtils.ts

// formats numbers as dollar values
const formatGDP = (v: number, includeCents = true): string => (
  v.toLocaleString(undefined, {
    style: 'currency',
    currency: 'USD',
    maximumFractionDigits: !includeCents ? 0 : undefined,
  })
);
 
// generate sequence of log tick labels and format them as decimal-less $
const MAX_EXPONENT = 6;
const EXPONENTS = Array.from(Array(MAX_EXPONENT).keys());
const BASE = 10;
const generateTickSequence = (vals: number[]): number[] => (
  EXPONENTS.flatMap((x: number) => vals.map((v) => v * (BASE ** x)))
);
const INITIAL_VALS = [1, 2, 5];
const LOG_SCALE_TICKS = [0, ...generateTickSequence(INITIAL_VALS)];
 
const formatXTick = ({ value }: { value: number }): string => (
  LOG_SCALE_TICKS.includes(value)
    ? formatGDP(value, false) // no decimal
    : ''
);
 
// show fewer x ticks when the chart is narrow. otherwise, use Graphique's default
const NARROW_WIDTH = 600;
const NUM_NARROW_TICKS = 2;
const getNumXTicks = (width: number): number | undefined => (
  width < NARROW_WIDTH ? NUM_NARROW_TICKS : undefined
);
 
const formatPop = (v: number): string => {
  const B = 1000000000;
  const M = 1000000;
 
  if (v >= B)
    return `${(v / B).toLocaleString(undefined, { maximumFractionDigits: 1 })}B`;
  if (v >= M)
    return `${(v / M)}M`;
  return v.toLocaleString();
};
 
export { formatGDP, formatXTick, getNumXTicks, formatPop };

gapMinder.module.css

.title {
  font-weight: 700;
}

Nice! This is definitely less compressed, and we now have dynamically formatted labels for both the x ticks and tooltip GDP values.

More encoding

Next, let’s encode more information that we wanted to include in our chart — coloring the points by continent and sizing by population.

We can do this simply by mapping properties in our data set to additional Aesthetic properties in aes (and removing the directly-applied attributes in GeomPoint).

We’ll also include a margin around the visualization area to account for the variety of point sizes and give our points some room to breathe along the boundaries.

GapMinder.tsx

import { GG, Labels, ScaleX, Tooltip } from '@graphique/graphique';
import { GeomPoint } from '@graphique/geom-point';
import { gapminder } from '@graphique/datasets';
import { scaleLog } from 'd3-scale';
import { formatGDP, formatXTick, getNumXTicks } from './formattingUtils';
import styles from './gapMinder.module.css';
 
const data = gapminder.filter(d => d.year === 2007);
 
export const GapMinderChart = () => {
  return (
    <GG
      data={data}
      aes={{
        x: (d) => d.gdpPercap,
        y: (d) => d.lifeExp,
        label: (d) => d.country,
        fill: (d) => d.continent,
        stroke: (d) => d.continent,
        size: (d) => d.pop,
      }}
      isContainerWidth
      margin={{ top: 30, right: 30, left: 35 }}
    >
      <GeomPoint
        attr={{ fillOpacity: 0.35, strokeOpacity: 0.4 }}
        focusedStyle={{ fillOpacity: 1 }}
      />
      <ScaleX
        type={scaleLog}
        format={formatXTick}
        numTicks={getNumXTicks}
      />
      <Tooltip xFormat={formatGDP} />
      <Labels
        x='GDP per capita'
        y='Life expectancy (years)'
        header={
          <span className={styles.title}>The health and wealth of nations</span>
        }
      />
    </GG>
  );
};

formattingUtils.ts

// formats numbers as dollar values
const formatGDP = (v: number, includeCents = true): string => (
  v.toLocaleString(undefined, {
    style: 'currency',
    currency: 'USD',
    maximumFractionDigits: !includeCents ? 0 : undefined,
  })
);
 
// generate sequence of log tick labels and format them as decimal-less $
const MAX_EXPONENT = 6;
const EXPONENTS = Array.from(Array(MAX_EXPONENT).keys());
const BASE = 10;
const generateTickSequence = (vals: number[]): number[] => (
  EXPONENTS.flatMap((x: number) => vals.map((v) => v * (BASE ** x)))
);
const INITIAL_VALS = [1, 2, 5];
const LOG_SCALE_TICKS = [0, ...generateTickSequence(INITIAL_VALS)];
 
const formatXTick = ({ value }: { value: number }): string => (
  LOG_SCALE_TICKS.includes(value)
    ? formatGDP(value, false) // no decimal
    : ''
);
 
// show fewer x ticks when the chart is narrow. otherwise, use Graphique's default
const NARROW_WIDTH = 600;
const NUM_NARROW_TICKS = 2;
const getNumXTicks = (width: number): number | undefined => (
  width < NARROW_WIDTH ? NUM_NARROW_TICKS : undefined
);
 
const formatPop = (v: number): string => {
  const B = 1000000000;
  const M = 1000000;
 
  if (v >= B)
    return `${(v / B).toLocaleString(undefined, { maximumFractionDigits: 1 })}B`;
  if (v >= M)
    return `${(v / M)}M`;
  return v.toLocaleString();
};
 
export { formatGDP, formatXTick, getNumXTicks, formatPop };

gapMinder.module.css

.title {
  font-weight: 700;
}

Notice how we conventiently created a few additional scales for the points — categorical fill and stroke scales for coloring based on the country’s continent and a continuous radius scale to size the points based on each country’s population

To make these new scales interpretable, we’ll add legends for them next.

Including legends

Adding legends to explain what the colors and sizes of the points represent is straightforward, and we can import these Geom-level legend components alongside GeomPoint.

GapMinder.tsx

import { 
  GG, Labels, ScaleX, Tooltip, LegendOrientation,
} from '@graphique/graphique';
import { GeomPoint, Legend, SizeLegend } from '@graphique/geom-point';
import { gapminder } from '@graphique/datasets';
import { scaleLog } from 'd3-scale';
import { formatGDP, formatPop, formatXTick, getNumXTicks } from './formattingUtils';
import styles from './gapMinder.module.css';
 
const data = gapminder.filter(d => d.year === 2007);
 
export const GapMinderChart = () => {
  return (
    <GG
      data={data}
      aes={{
        x: (d) => d.gdpPercap,
        y: (d) => d.lifeExp,
        label: (d) => d.country,
        fill: (d) => d.continent,
        size: (d) => d.pop,
      }}
      margin={{ top: 30, right: 30, left: 35 }}
      isContainerWidth
    >
      <GeomPoint attr={{ fillOpacity: 0.35, strokeOpacity: 0.4 }} />
      <ScaleX
        type={scaleLog}
        format={formatXTick}
        numTicks={getNumXTicks}
      />
      <Tooltip xFormat={formatGDP} />
      <Labels
        x='GDP per capita'
        y='Life expectancy (years)'
        header={
          <span className={styles.title}>
            The health and wealth of nations
          </span>
        }
      />
      <div className={styles.legends}>
        <Legend
          orientation={LegendOrientation.H}
          title={<span className={styles['legend-title']}>Continent</span>}
        />
        <SizeLegend
          title={<span className={styles['legend-title']}>Population</span>}
          format={formatPop}
        />
      </div>
    </GG>
  );
};

formattingUtils.ts

// formats numbers as dollar values
const formatGDP = (v: number, includeCents = true): string => (
  v.toLocaleString(undefined, {
    style: 'currency',
    currency: 'USD',
    maximumFractionDigits: !includeCents ? 0 : undefined,
  })
);
 
// generate sequence of log tick labels and format them as decimal-less $
const MAX_EXPONENT = 6;
const EXPONENTS = Array.from(Array(MAX_EXPONENT).keys());
const BASE = 10;
const generateTickSequence = (vals: number[]): number[] => (
  EXPONENTS.flatMap((x: number) => vals.map((v) => v * (BASE ** x)))
);
const INITIAL_VALS = [1, 2, 5];
const LOG_SCALE_TICKS = [0, ...generateTickSequence(INITIAL_VALS)];
 
const formatXTick = ({ value }: { value: number }): string => (
  LOG_SCALE_TICKS.includes(value)
    ? formatGDP(value, false) // no decimal
    : ''
);
 
// show fewer x ticks when the chart is narrow. otherwise, use Graphique's default
const NARROW_WIDTH = 600;
const NUM_NARROW_TICKS = 2;
const getNumXTicks = (width: number): number | undefined => (
  width < NARROW_WIDTH ? NUM_NARROW_TICKS : undefined
);
 
const formatPop = (v: number): string => {
  const B = 1000000000;
  const M = 1000000;
 
  if (v >= B)
    return `${(v / B).toLocaleString(undefined, { maximumFractionDigits: 1 })}B`;
  if (v >= M)
    return `${(v / M)}M`;
  return v.toLocaleString();
};
 
export { formatGDP, formatXTick, getNumXTicks, formatPop };

gapMinder.module.css

.title {
  font-weight: 700;
}
 
.legends {
  display: flex;
  justify-content: flex-end;
  align-items: flex-start;
  column-gap: 1.5rem;
  padding: 0.5rem 0 1rem 0;
}
 
.legend-title {
  font-size: 0.8rem;
  font-weight: 700;
}

These legends are automatically configured based on the data we’ve passed in and the Aesthetic mappings we’ve defined. If you didn’t already, try clicking on the continent legend members and see what happens.

Custom `Theme`

Before we go any further, let’s make the visualization area a little more minimal by removing the grid lines and only drawing the x/y axis lines.

GapMinder.tsx

import { 
  GG, Labels, ScaleX, Tooltip, LegendOrientation, Theme,
} from '@graphique/graphique';
import { GeomPoint, Legend, SizeLegend } from '@graphique/geom-point';
import { gapminder } from '@graphique/datasets';
import { scaleLog } from 'd3-scale';
import { formatGDP, formatPop, formatXTick, getNumXTicks } from './formattingUtils';
import styles from './gapMinder.module.css';
 
const data = gapminder.filter(d => d.year === 2007);
 
export const GapMinderChart = () => {
  return (
    <GG
      data={data}
      aes={{
        x: (d) => d.gdpPercap,
        y: (d) => d.lifeExp,
        label: (d) => d.country,
        fill: (d) => d.continent,
        size: (d) => d.pop,
      }}
      margin={{ top: 30, right: 30, left: 35 }}
      isContainerWidth
    >
      <GeomPoint attr={{ fillOpacity: 0.35, strokeOpacity: 0.4 }} />
      <ScaleX
        type={scaleLog}
        format={formatXTick}
        numTicks={getNumXTicks}
      />
      <Tooltip xFormat={formatGDP} />
      <Labels
        x='GDP per capita'
        y='Life expectancy (years)'
        header={
          <span className={styles.title}>
            The health and wealth of nations
          </span>
        }
      />
      <div className={styles.legends}>
        <Legend
          orientation={LegendOrientation.H}
          title={<span className={styles['legend-title']}>Continent</span>}
        />
        <SizeLegend
          title={<span className={styles['legend-title']}>Population</span>}
          format={formatPop}
        />
      </div>
      <Theme grid={{ stroke: null }} axis={{ showAxisLine: true }} />
    </GG>
  );
};

formattingUtils.ts

// formats numbers as dollar values
const formatGDP = (v: number, includeCents = true): string => (
  v.toLocaleString(undefined, {
    style: 'currency',
    currency: 'USD',
    maximumFractionDigits: !includeCents ? 0 : undefined,
  })
);
 
// generate sequence of log tick labels and format them as decimal-less $
const MAX_EXPONENT = 6;
const EXPONENTS = Array.from(Array(MAX_EXPONENT).keys());
const BASE = 10;
const generateTickSequence = (vals: number[]): number[] => (
  EXPONENTS.flatMap((x: number) => vals.map((v) => v * (BASE ** x)))
);
const INITIAL_VALS = [1, 2, 5];
const LOG_SCALE_TICKS = [0, ...generateTickSequence(INITIAL_VALS)];
 
const formatXTick = ({ value }: { value: number }): string => (
  LOG_SCALE_TICKS.includes(value)
    ? formatGDP(value, false) // no decimal
    : ''
);
 
// show fewer x ticks when the chart is narrow. otherwise, use Graphique's default
const NARROW_WIDTH = 600;
const NUM_NARROW_TICKS = 2;
const getNumXTicks = (width: number): number | undefined => (
  width < NARROW_WIDTH ? NUM_NARROW_TICKS : undefined
);
 
const formatPop = (v: number): string => {
  const B = 1000000000;
  const M = 1000000;
 
  if (v >= B)
    return `${(v / B).toLocaleString(undefined, { maximumFractionDigits: 1 })}B`;
  if (v >= M)
    return `${(v / M)}M`;
  return v.toLocaleString();
};
 
export { formatGDP, formatXTick, getNumXTicks, formatPop };

gapMinder.module.css

.title {
  font-weight: 700;
}
 
.legends {
  display: flex;
  justify-content: flex-end;
  align-items: flex-start;
  column-gap: 1.5rem;
  padding: 0.5rem 0 1rem 0;
}
 
.legend-title {
  font-size: 0.8rem;
  font-weight: 700;
}

This is an informative and polished chart at this point, but let’s see if we can make it even more engaging and descriptive by customizing what happens when a user focuses/hovers over a point.

Stateful interactions

Instead of the default tooltip, let’s show the focused country’s GDP and life expectancy through the years. We can add this historical context in the form of a connected scatterplot by conditionally rendering separate Geoms based on the currently-focused country.

Introducing state

We can use React’s useState hook to directly modify and respond to changes in our visualization’s state. Let’s start by removing the tooltip for GeomPoint and instead use GeomLabel to show only the focused country’s name. We could create this label with a customized tooltip, but why we might start this way should be clear as we continue.

GapMinder.tsx

import { useState } from 'react';
import {
  GG, Labels, ScaleX, Tooltip, LegendOrientation, Theme,
} from '@graphique/graphique';
import { GeomPoint, Legend, SizeLegend } from '@graphique/geom-point';
import { GeomLabel } from '@graphique/geom-label';
import { gapminder, type GapMinder } from '@graphique/datasets';
import { scaleLog } from 'd3-scale';
import { formatPop, formatXTick, getNumXTicks } from './formattingUtils';
import styles from './gapMinder.module.css';
 
const data = gapminder.filter(d => d.year === 2007);
 
export const GapMinderChart = () => {
  const [focusedCountry, setFocusedCountry] = useState<GapMinder | undefined>();
 
  return (
    <GG
      data={data}
      aes={{
        x: (d) => d.gdpPercap,
        y: (d) => d.lifeExp,
        label: (d) => d.country,
        fill: (d) => d.continent,
        stroke: (d) => d.continent,
        size: (d) => d.pop,
      }}
      margin={{ top: 30, right: 30, left: 35 }}
      isContainerWidth
    >
      <GeomPoint<GapMinder>
        attr={{ fillOpacity: 0.35, strokeOpacity: 0.4 }}
        focusedStyle={{ fillOpacity: 1 }}
        onDatumFocus={(d) => setFocusedCountry(d?.[0])}
        onExit={() => setFocusedCountry(undefined)}
      />
      {focusedCountry && (
        <GeomLabel
          data={[focusedCountry]}
          attr={{
            fill: 'currentColor',
            stroke: themedColor, // (defined outside of demo)
            strokeOpacity: 0.7,
            fontSize: '0.8rem',
          }}
          isAnimated={false}
        />
      )}
      <ScaleX type={scaleLog} format={formatXTick} numTicks={getNumXTicks} />
      <Tooltip content={() => null} />
      <Labels
        x="GDP per capita"
        y="Life expectancy (years)"
        header={
          <span className={styles.title}>
            The health and wealth of nations
          </span>
        }
      />
      <div className={styles.legends}>
        <Legend
          orientation={LegendOrientation.H}
          title={<span className={styles['legend-title']}>Continent</span>}
        />
        <SizeLegend
          title={<span className={styles['legend-title']}>Population</span>}
          format={formatPop}
        />
      </div>
      <Theme grid={{ stroke: null }} axis={{ showAxisLine: true }} />
    </GG>
  );
};

formattingUtils.ts

// formats numbers as dollar values
const formatGDP = (v: number, includeCents = true): string => (
  v.toLocaleString(undefined, {
    style: 'currency',
    currency: 'USD',
    maximumFractionDigits: !includeCents ? 0 : undefined,
  })
);
 
// generate sequence of log tick labels and format them as decimal-less $
const MAX_EXPONENT = 6;
const EXPONENTS = Array.from(Array(MAX_EXPONENT).keys());
const BASE = 10;
const generateTickSequence = (vals: number[]): number[] => (
  EXPONENTS.flatMap((x: number) => vals.map((v) => v * (BASE ** x)))
);
const INITIAL_VALS = [1, 2, 5];
const LOG_SCALE_TICKS = [0, ...generateTickSequence(INITIAL_VALS)];
 
const formatXTick = ({ value }: { value: number }): string => (
  LOG_SCALE_TICKS.includes(value)
    ? formatGDP(value, false) // no decimal
    : ''
);
 
// show fewer x ticks when the chart is narrow. otherwise, use Graphique's default
const NARROW_WIDTH = 600;
const NUM_NARROW_TICKS = 2;
const getNumXTicks = (width: number): number | undefined => (
  width < NARROW_WIDTH ? NUM_NARROW_TICKS : undefined
);
 
const formatPop = (v: number): string => {
  const B = 1000000000;
  const M = 1000000;
 
  if (v >= B)
    return `${(v / B).toLocaleString(undefined, { maximumFractionDigits: 1 })}B`;
  if (v >= M)
    return `${(v / M)}M`;
  return v.toLocaleString();
};
 
export { formatGDP, formatXTick, getNumXTicks, formatPop };

gapMinder.module.css

.title {
  font-weight: 700;
}
 
.legends {
  display: flex;
  justify-content: flex-end;
  align-items: flex-start;
  column-gap: 1.5rem;
  padding: 0.5rem 0 1rem 0;
}
 
.legend-title {
  font-size: 0.8rem;
  font-weight: 700;
}

This is a good start to build off of for our connected scatterplot on focus, but it’ll take some work to manage state more effectively — notice what happens when focusing data after using the continent legend to filter out points 😬.

React is rerendering our chart (with its defaults applied) every time a country is focused (and our component’s state is updated). To prevent this, we can also use a similar approach with our legend/legend selections and manage those directly.

Fixed scales

Now that we’re starting to manage our visualization’s state on our own (outside of Graphique), we can also do the same for our legend and control the filtering behavior more directly. You can think of this as turning autopilot off.

For our connected scatterplot, we’ll also want to account for the full range of countries’ x/y values (or at least the full range based on the selected continents), not just for the single year we’re visualizing points for now. To do this, we can create a fixed x scale and a fixed y scale with custom domains.

GapMinder.tsx

import { useState, useMemo } from 'react';
import {
  GG, Labels, ScaleX, ScaleY, ScaleFill, ScaleStroke, Tooltip, LegendOrientation, Theme,
} from '@graphique/graphique';
import { GeomPoint, Legend, SizeLegend } from '@graphique/geom-point';
import { GeomLabel } from '@graphique/geom-label';
import { gapminder, type GapMinder } from '@graphique/datasets';
import { scaleLog } from 'd3-scale';
import { extent } from 'd3-array';
import { formatPop, formatXTick, getNumXTicks } from './formattingUtils';
import styles from './gapMinder.module.css';
 
const data = gapminder.filter(d => d.year === 2007);
const continents = Array.from(new Set(data.map((d) => d.continent))).sort();
 
export const GapMinderChart = () => {
  const [focusedCountry, setFocusedCountry] = useState<GapMinder | undefined>();
  const [selectedContinents, setSelectedContinents] = useState(continents);
 
  const includedCountries = useMemo(
    () => data.filter((d) => selectedContinents.includes(d.continent)),
    [selectedContinents],
  );
 
  const xExtent = useMemo(
    () =>
      extent(
        gapminder.filter((d) => selectedContinents.includes(d.continent)),
        (d) => d.gdpPercap,
      ),
    [selectedContinents],
  );
 
  const yExtent = useMemo(
    () =>
      extent(
        gapminder.filter((d) => selectedContinents.includes(d.continent)),
        (d) => d.lifeExp,
      ),
    [selectedContinents],
  );
 
  return (
    <GG
      data={includedCountries}
      aes={{
        x: (d) => d.gdpPercap,
        y: (d) => d.lifeExp,
        label: (d) => d.country,
        fill: (d) => d.continent,
        stroke: (d) => d.continent,
        size: (d) => d.pop,
      }}
      margin={{ top: 30, right: 30, left: 35 }}
      isContainerWidth
    >
      <GeomPoint<GapMinder>
        key="countries"
        aes={{ key: (d) => d.country }}
        attr={{ fillOpacity: 0.35, strokeOpacity: 0.4 }}
        focusedStyle={{ fillOpacity: 1 }}
        onDatumFocus={(d) => setFocusedCountry(d?.[0])}
        onExit={() => setFocusedCountry(undefined)}
      />
      {focusedCountry && (
        <GeomLabel
          data={[focusedCountry]}
          attr={{
            fill: 'currentColor',
            stroke: themedColor, // (defined outside of demo)
            strokeOpacity: 0.7,
            fontSize: '0.8rem',
          }}
          isAnimated={false}
        />
      )}
      <ScaleX
        type={scaleLog}
        format={formatXTick}
        numTicks={getNumXTicks}
        domain={xExtent}
      />
      <ScaleY domain={yExtent} />
      <ScaleFill domain={continents} />
      <ScaleStroke domain={continents} />
      <Tooltip content={() => null} />
      <Labels
        x="GDP per capita"
        y="Life expectancy (years)"
        header={
          <span className={styles.title}>
            The health and wealth of nations
          </span>
        }
      />
      <div className={styles.legends}>
        <Legend
          orientation={LegendOrientation.H}
          title={<span className={styles['legend-title']}>Continent</span>}
          onSelection={(v) => {
            setSelectedContinents((prev) => {
              if (prev.includes(v) && prev.length === 1) {
                return continents
              }
              if (prev.includes(v)) {
                return prev.filter((p) => p !== v)
              }
              return [...prev, v]
            })
 
            if (focusedCountry?.continent === v) {
              setFocusedCountry(undefined)
            }
          }}
        />
        <SizeLegend
          title={<span className={styles['legend-title']}>Population</span>}
          format={formatPop}
        />
      </div>
      <Theme grid={{ stroke: null }} axis={{ showAxisLine: true }} />
    </GG>
  );
};

formattingUtils.ts

// formats numbers as dollar values
const formatGDP = (v: number, includeCents = true): string => (
  v.toLocaleString(undefined, {
    style: 'currency',
    currency: 'USD',
    maximumFractionDigits: !includeCents ? 0 : undefined,
  })
);
 
// generate sequence of log tick labels and format them as decimal-less $
const MAX_EXPONENT = 6;
const EXPONENTS = Array.from(Array(MAX_EXPONENT).keys());
const BASE = 10;
const generateTickSequence = (vals: number[]): number[] => (
  EXPONENTS.flatMap((x: number) => vals.map((v) => v * (BASE ** x)))
);
const INITIAL_VALS = [1, 2, 5];
const LOG_SCALE_TICKS = [0, ...generateTickSequence(INITIAL_VALS)];
 
const formatXTick = ({ value }: { value: number }): string => (
  LOG_SCALE_TICKS.includes(value)
    ? formatGDP(value, false) // no decimal
    : ''
);
 
// show fewer x ticks when the chart is narrow. otherwise, use Graphique's default
const NARROW_WIDTH = 600;
const NUM_NARROW_TICKS = 2;
const getNumXTicks = (width: number): number | undefined => (
  width < NARROW_WIDTH ? NUM_NARROW_TICKS : undefined
);
 
const formatPop = (v: number): string => {
  const B = 1000000000;
  const M = 1000000;
 
  if (v >= B)
    return `${(v / B).toLocaleString(undefined, { maximumFractionDigits: 1 })}B`;
  if (v >= M)
    return `${(v / M)}M`;
  return v.toLocaleString();
};
 
export { formatGDP, formatXTick, getNumXTicks, formatPop };

gapMinder.module.css

.title {
  font-weight: 700;
}
 
.legends {
  display: flex;
  justify-content: flex-end;
  align-items: flex-start;
  column-gap: 1.5rem;
  padding: 0.5rem 0 1rem 0;
}
 
.legend-title {
  font-size: 0.8rem;
  font-weight: 700;
}

Scales updated! Besides the expanded x and y scales, the fill and stroke scales (and continent names in the legend) are now ordered alphabetically, and any filters applied with the continent legend remain applied across interactions. We left the radius scale as it was, but if we wanted to, we could’ve just as easily fixed that one, too.

More conditional Geoms

Nearly there! This is where we add the connected scatterplot for each focused country to show the journey it’s taken through history.

We already added a conditional GeomLabel, now let’s add GeomLine and another GeomPoint based on a very similar condition.

GapMinder.tsx

import { useState, useMemo } from 'react';
import {
  GG, Labels, ScaleX, ScaleY, ScaleFill, ScaleStroke, Tooltip, LegendOrientation, Theme,
} from '@graphique/graphique';
import { GeomPoint, Legend, SizeLegend } from '@graphique/geom-point';
import { GeomLabel } from '@graphique/geom-label';
import { GeomLine } from '@graphique/geom-line';
import { gapminder, type GapMinder } from '@graphique/datasets';
import { scaleLog } from 'd3-scale';
import { extent } from 'd3-array';
import { formatPop, formatXTick, getNumXTicks } from './formattingUtils';
import styles from './gapMinder.module.css';
 
const data = gapminder.filter(d => d.year === 2007);
const continents = Array.from(new Set(data.map((d) => d.continent))).sort();
 
export const GapMinderChart = () => {
  const [focusedCountry, setFocusedCountry] = useState<GapMinder | undefined>();
  const [selectedContinents, setSelectedContinents] = useState(continents);
 
  const focusedCountryTrend = useMemo(
    () => gapminder.filter((d) => d.country === focusedCountry?.country),
    [focusedCountry],
  );
 
  const includedCountries = useMemo(
    () => data.filter((d) => selectedContinents.includes(d.continent)),
    [selectedContinents],
  );
 
  const xExtent = useMemo(
    () =>
      extent(
        gapminder.filter((d) => selectedContinents.includes(d.continent)),
        (d) => d.gdpPercap,
      ),
    [selectedContinents],
  );
 
  const yExtent = useMemo(
    () =>
      extent(
        gapminder.filter((d) => selectedContinents.includes(d.continent)),
        (d) => d.lifeExp,
      ),
    [selectedContinents],
  );
 
  return (
    <GG
      data={includedCountries}
      aes={{
        x: (d) => d.gdpPercap,
        y: (d) => d.lifeExp,
        label: (d) => d.country,
        fill: (d) => d.continent,
        stroke: (d) => d.continent,
        size: (d) => d.pop,
      }}
      margin={{ top: 30, right: 30, left: 35 }}
      isContainerWidth
    >
      {focusedCountryTrend && (
        <>
          <GeomLine
            data={focusedCountryTrend}
            showTooltip={false}
            attr={{ strokeWidth: 2, strokeOpacity: 0.8 }}
            isAnimated={false}
          />
          <GeomPoint
            data={focusedCountryTrend}
            showTooltip={false}
            attr={{ fill: themedColor, fillOpacity: 0.8, r: 2.3 }}
            isAnimated={false}
          />
        </>
      )}
      <GeomPoint<GapMinder>
        key="countries"
        aes={{ key: (d) => d.country }}
        attr={{ fillOpacity: 0.35, strokeOpacity: 0.4 }}
        focusedStyle={{ fillOpacity: 1 }}
        onDatumFocus={(d) => setFocusedCountry(d?.[0])}
        onExit={() => setFocusedCountry(undefined)}
      />
      {focusedCountry && (
        <GeomLabel
          data={[focusedCountry]}
          attr={{
            fill: 'currentColor',
            stroke: themedColor, // (defined outside of demo)
            strokeOpacity: 0.7,
            fontSize: '0.8rem',
          }}
          isAnimated={false}
        />
      )}
      <ScaleX
        type={scaleLog}
        format={formatXTick}
        numTicks={getNumXTicks}
        domain={xExtent}
      />
      <ScaleY domain={yExtent} />
      <ScaleFill domain={continents} />
      <ScaleStroke domain={continents} />
      <Tooltip content={() => null} />
      <Labels
        x="GDP per capita"
        y="Life expectancy (years)"
        header={
          <span className={styles.title}>
            The health and wealth of nations
          </span>
        }
      />
      <div className={styles.legends}>
        <Legend
          orientation={LegendOrientation.H}
          title={<span className={styles['legend-title']}>Continent</span>}
          onSelection={(v) => {
            setSelectedContinents((prev) => {
              if (prev.includes(v) && prev.length === 1) {
                return continents
              }
              if (prev.includes(v)) {
                return prev.filter((p) => p !== v)
              }
              return [...prev, v]
            })
 
            if (focusedCountry?.continent === v) {
              setFocusedCountry(undefined)
            }
          }}
        />
        <SizeLegend
          title={<span className={styles['legend-title']}>Population</span>}
          format={formatPop}
        />
      </div>
      <Theme grid={{ stroke: null }} axis={{ showAxisLine: true }} />
    </GG>
  );
};

formattingUtils.ts

// formats numbers as dollar values
const formatGDP = (v: number, includeCents = true): string => (
  v.toLocaleString(undefined, {
    style: 'currency',
    currency: 'USD',
    maximumFractionDigits: !includeCents ? 0 : undefined,
  })
);
 
// generate sequence of log tick labels and format them as decimal-less $
const MAX_EXPONENT = 6;
const EXPONENTS = Array.from(Array(MAX_EXPONENT).keys());
const BASE = 10;
const generateTickSequence = (vals: number[]): number[] => (
  EXPONENTS.flatMap((x: number) => vals.map((v) => v * (BASE ** x)))
);
const INITIAL_VALS = [1, 2, 5];
const LOG_SCALE_TICKS = [0, ...generateTickSequence(INITIAL_VALS)];
 
const formatXTick = ({ value }: { value: number }): string => (
  LOG_SCALE_TICKS.includes(value)
    ? formatGDP(value, false) // no decimal
    : ''
);
 
// show fewer x ticks when the chart is narrow. otherwise, use Graphique's default
const NARROW_WIDTH = 600;
const NUM_NARROW_TICKS = 2;
const getNumXTicks = (width: number): number | undefined => (
  width < NARROW_WIDTH ? NUM_NARROW_TICKS : undefined
);
 
const formatPop = (v: number): string => {
  const B = 1000000000;
  const M = 1000000;
 
  if (v >= B)
    return `${(v / B).toLocaleString(undefined, { maximumFractionDigits: 1 })}B`;
  if (v >= M)
    return `${(v / M)}M`;
  return v.toLocaleString();
};
 
export { formatGDP, formatXTick, getNumXTicks, formatPop };

gapMinder.module.css

.title {
  font-weight: 700;
}
 
.legends {
  display: flex;
  justify-content: flex-end;
  align-items: flex-start;
  column-gap: 1.5rem;
  padding: 0.5rem 0 1rem 0;
}
 
.legend-title {
  font-size: 0.8rem;
  font-weight: 700;
}

This is the visualization we were hoping to create! Pretty useful (especially when combined with React’s state management), relatively engaging and informative, and not too painful to make. The only thing left is a matter of organization/composition and structuring this relatively complex visualization in a more “idiomatic React” way.

Finished product

As a last step, instead of one big component that does everything, let’s extract some of this functionality into separate React components and handle our related state with a React Context.

That’s all for now, but this should open up the world of possibilities when using Graphique to create interactive visualizations in your React UIs. Enjoy!

crimes

Walk-through

Show me the data

A layered approach

The base

Draw the countries

Starting to customize

Use and format log x scale

More encoding

Including legends

Custom Theme

Stateful interactions

Introducing state

Fixed scales

More conditional Geoms

Finished product

Custom `Theme`