useChart

useChart is an optional hook that holds a chart's data and series. Its helpers sum values, find the minimum and maximum, format numbers and dates, and look up theme colors.

Usage

Code
import { useChart } from '@leverui/components';
Code
const chart = useChart({
  data: [
    { date: '2024-01-01', revenue: 1000 },
    { date: '2024-01-02', revenue: 2000 },
    { date: '2024-01-03', revenue: 3000 },
  ],
  series: [{ name: 'revenue', color: 'blue.500' }],
});

Series labels

label is the name shown in the legend and the tooltip. Without it, they show name.

Code
const chart = useChart({
  data,
  series: [{ name: 'revenue', label: 'Revenue', color: 'blue.500' }],
});

Dynamic data

Passing the options directly reads the data once. If the data can change later, such as rows loaded from a server or filtered by the user, wrap the options in a function. useChart then reads them again on every change, and the chart redraws.

Code
const [rows, setRows] = createSignal([{ date: '2024-01-01', revenue: 1000 }]);

// Redraws every time setRows runs.
const chart = useChart(() => ({
  data: rows(),
  series: [{ name: 'revenue', color: 'blue.500' }],
}));

Without the function, rows() is read only when the chart is created, and later changes never reach it.

Code
// Stays on the first rows forever.
const chart = useChart({
  data: rows(),
  series: [{ name: 'revenue', color: 'blue.500' }],
});

Series

getKey

Returns a field name that TypeScript checks. chart.key is the same helper.

Code
const key = chart.getKey('revenue'); // 'revenue'

Aggregation

getTotal

Code
console.log(chart.getTotal('revenue')); // 6000

getMin

Code
console.log(chart.getMin('revenue')); // 1000

getMax

Code
console.log(chart.getMax('revenue')); // 3000

getValuePercent

A value as a percentage of the total for its field.

Code
const percentage = chart.getValuePercent('revenue', 3000);
console.log(percentage); // 50

Pass a range as the third argument to measure against it.

Code
console.log(chart.getValuePercent('revenue', 2000, [0, 4000])); // 50

The range can also be a function. It gets the field's smallest and largest values as { min, max } and returns the range.

Formatting

formatNumber

Takes any Intl.NumberFormatOptions.

Code
const format = chart.formatNumber({ style: 'currency', currency: 'USD' });
console.log(format(1000)); // "$1,000.00"

formatDate

Takes any Intl.DateTimeFormatOptions.

Code
const formatDate = chart.formatDate({ year: 'numeric', month: 'short' });
console.log(formatDate('2024-03-28')); // "Mar 2024"

A date with no time, such as 2024-03-28, shows as that day in every time zone. A date with a time shows in the reader's time zone, unless you pass timeZone.

Both helpers use the locale of the nearest LocaleProvider, or en-US without one.

Design tokens

Use these to give a chart a color, size, or spacing from the theme. Token names such as blue.500 are built in. A token name becomes its CSS variable. A plain CSS value, such as #ccc or 2rem, is returned as is.

A color token is a palette and a shade: blue.500 is the blue palette, shade 500, which is --leverui-colors-blue-500. See every color on the Colors page. Sizes and spacing are listed in the size and spacing references.

To add a color of your own, define its variable in CSS, then pass its name: --leverui-colors-brand-500 is brand.500.

color

Code
chart.color('blue.500'); // var(--leverui-colors-blue-500)
chart.color('#ccc'); // #ccc

size

Code
const chartSize = chart.size('4'); // var(--leverui-sizes-4)

spacing

Code
const chartPadding = chart.spacing('4'); // var(--leverui-spacing-4)

Sorting

direction is asc or desc. Numbers sort by value, everything else as text.

Code
const chart = useChart({
  data: [
    { date: '2024-01-01', revenue: 1000 },
    { date: '2024-01-02', revenue: 2000 },
    { date: '2024-01-03', revenue: 3000 },
  ],
  sort: { by: 'date', direction: 'asc' },
  series: [{ name: 'revenue', color: 'blue.500' }],
});

chart.data holds the sorted rows.

Highlighting

The chart object remembers one highlighted series.

highlightedSeries

Name of the highlighted series, or null.

setHighlightedSeries

Pass null to clear it.

Code
chart.setHighlightedSeries('revenue');

isHighlightedSeries

Code
const isActive = chart.isHighlightedSeries('revenue'); // true

getSeriesOpacity

1 for the highlighted series, 0.2 for the others, undefined when nothing is highlighted. A second argument replaces 0.2.

Code
chart.setHighlightedSeries('revenue');

chart.getSeriesOpacity('revenue'); // 1
chart.getSeriesOpacity('costs'); // 0.2

All helpers

HelperPurpose
idUnique ID for this chart.
dataChart data, sorted if you set sort.
seriesSeries you passed in.
key(name), getKey(name)Field name, checked by TypeScript.
getSeries(name)Details of one series.
getSeriesOpacity(name, fallback)Opacity to draw a series with.
groupBy(key)Rows split into groups that share a value.
getTotal(key)Sum of a field.
getMin(key)Smallest value of a field.
getMax(key)Largest value of a field.
getValuePercent(key, value, domain)A value as a percentage.
formatNumber(options)Function that formats numbers.
formatDate(options)Function that formats date strings.
color(key)CSS variable for a color token.
size(key)CSS variable for a size token.
spacing(key)CSS variable for a spacing token.
highlightedSeriesName of the highlighted series, or null.
setHighlightedSeries(name)Set the highlighted series.
isHighlightedSeries(name)Whether a series is highlighted.