Documentation

Introduction Get Started Theming Tokens Roadmap Changelog llms.txt

Components

Charts

X AI

Kiosk

Interactive

Interactive charts respond to the reader, with legends, cursors, brushes and handles that select, filter or move what the chart shows.

Code

Legends, selection, brushes and zoom work the same way on every TanStack chart, through the kit's Chart components. The options below go into the chart's TanStack definition, written the way TanStack documents it.

Install

npx antuikit@latest init

npx antuikit@latest add tanstack-chart

The first command installs AntuikitProvider and the theme tokens. The second adds the chart components and TanStack Charts itself.

Controlled state

Every control on this page keeps its value in your state, not in the chart. controlledSignal pairs the current value with a callback that receives the next one. Store it, and rebuild the definition from it in useMemo, the way a controlled input works.

import { controlledSignal } from "@tanstack/charts/interaction/signal"

const [visible, setVisible] = useState<readonly string[]>(industries)

const definition = useMemo(

() =>

defineChart({

// ...marks and scales

color: {

domain: industries,

legend: interactiveColorLegend({

visible: controlledSignal(visible, setVisible),

}),

[visible],

)

The callback's second argument carries a reason. For a drag it is preview while the pointer moves, then commit or cancel. Keep the chart on the last committed value and use previews for live text, so a cancelled drag puts everything back.

Toggle series from the legend

interactiveColorLegend replaces the color legend with buttons that hide and show series. It works on marks whose color names the series.

import { interactiveColorLegend } from "@tanstack/charts/legend"

color: {

domain: industries,

legend: interactiveColorLegend({

visible: controlledSignal(visible, setVisible),

placement: "bottom",

ariaLabel: "Series visibility",

}),

}

A hidden series keeps its color and its place in the scale domains. Set the value scale's domain yourself when the chart should not rescale at all.
hover: "series" highlights a series while the pointer is on its button or the button has focus.

Select a point

keyedSelection turns a click, Enter or Space on a point into a selected key. whenSelected wraps a mark so it draws only the selected point, which makes it the highlight. Anything else on the page, such as a table, can set the same key.

import { keyedSelection, whenSelected } from "@tanstack/charts/selection"

const [selectedId, setSelectedId] = useState<string | null>(null)

const definition = useMemo(() => {

const selection = keyedSelection<Penguin, string, number, number>({

selected: controlledSignal(selectedId, (next) => setSelectedId(next)),

key: (penguin) => penguin.id,

})

return defineChart({

marks: [

dot(penguins, { x: "flipper", y: "mass", key: "id", r: 4.5 }),

whenSelected(

dot(penguins, { x: "flipper", y: "mass", key: "id", r: 7, strokeWidth: 2 }),

selection,

scales: { x: { scale: scaleLinear }, y: { scale: scaleLinear } },

selection,

})

}, [selectedId])

<Table

rowKey="id"

dataSource={penguins}

rowSelection={{

type: "radio",

selectedRowKeys: selectedId ? [selectedId] : [],

onChange: (keys) => setSelectedId(String(keys[0] ?? "") || null),

}}

A click on empty space proposes null. Add a Clear selection button that sets the same state, for readers who do not know that.

Axis pointer and synchronized cursors

focusGuideX draws a line at the focused x value. With focus: "group-x" and no distance limit it snaps to the nearest date from anywhere in the plot, and one tooltip lists every series there.

import { focusGuideX } from "@tanstack/charts/focus/guide"

marks: [

// ...lines and dots

focusGuideX(rows, {

x: "date",

y: "unemployed",

z: "industry",

key: "id",

xRule: { stroke: chartColors.axis, strokeDasharray: "4 4" },

}),

focus: "group-x",

focusRing: false,

maxFocusDistance: Number.POSITIVE_INFINITY,

To mark the same date in two stacked charts, draw both as views of one viewGrid and give the second share: { x: "current" }, the id of the first. For charts that are separate components, create one controller with createChartCursor() and pass it to each definition's cursor option with use: cursorHost, mode: "focus" and match: "x".

Free cursor

continuousCursor follows any position in the plot, between data points too. Both scales must be numeric or time scales. Hovering sends previews, and a click commits a position and pins the cursor.

import { continuousCursor } from "@tanstack/charts/interaction/cursor"

controls: [

continuousCursor({

position: controlledSignal(pinned, (next, { reason }) => {

if (reason.type === "preview") {

if (next) setHovered(next)

return

}

setPinned(next)

}),

xLabel: { format: (value) => `${Math.round(value)} hp` },

yLabel: { side: "start", format: (value) => `${Math.round(value)} mpg` },

}),

keyboard: false,

The cursor has no keyboard control of its own. Put a Slider for each axis next to the chart and write to the same state.

Range brush

brushX lets the reader drag a range along the x axis. With values, both ends snap to those values and each handle becomes a slider for the keyboard.

import { brushX } from "@tanstack/charts/interaction/brush"

const [committed, setCommitted] = useState({ start: dates[3], end: dates[5] })

const [range, setRange] = useState(committed)

controls: [

brushX({

range: controlledSignal(committed, (next, { reason }) => {

setRange(next)

if (reason.type !== "preview") setCommitted(next)

}),

values: dates,

ariaLabel: "Month range",

startAriaLabel: "Range start",

endAriaLabel: "Range end",

format: (date) => formatMonth(date),

}),

keyboard: false,

focusRing: false,

range follows the drag for the summary text, and committed drives the chart. keyboard: false on the definition turns off point navigation, so the brush is the chart's only control. For focus and context, put the brush on a small overview chart and use committed as the domain of a larger one.

Zoom and pan

zoomX proposes a new x window as the reader zooms and pans. Use the window as the x scale's domain, and set clip so marks outside it are cut off.

import { zoomX } from "@tanstack/charts/interaction/zoom"

const [window, setWindow] = useState({ start: extent[0], end: extent[1] })

defineChart({

clip: true,

scales: {

x: { scale: scaleUtc().domain([window.start, window.end]) },

y: { scale: scaleLinear },

controls: [

zoomX({

window: controlledSignal(window, setWindow),

extent,

scaleExtent: [1, 8],

ariaLabel: "Zoomable time window",

}),

})

<Button onClick={() => setWindow({ start: extent[0], end: extent[1] })}>Reset zoom</Button>

extent is the full range, and scaleExtent caps the zoom at eight times here.
The wheel zooms only once the chart has focus. On a page that scrolls, wheelActivation: "modifier" zooms while Control or Command is held instead. Avoid "always" there.
Pass every proposal to state, previews included, so the chart moves with the gesture.

Handles and scrubbers

handleX is one draggable value on a track, such as a playhead or an event's end date. Its value must be one of values. cross places the track below the plot with edge, or across it at a y value.

import { handleX } from "@tanstack/charts/interaction/handle"

controls: [

handleX({

value: controlledSignal(dates[frame], (next, { reason }) => {

setPlaying(false)

if (reason.type === "commit") setFrame(dates.indexOf(next))

}),

values: dates,

cross: { edge: "bottom", offset: 34 },

ariaLabel: "Timeline frame",

format: (date) => formatDay(date),

}),

The chart does not play anything itself. Keep the timer in your component, stop it when the reader drags or reaches the last value, and show a Play and Pause button.

Live data

Append rows to your state and rebuild the definition. Keep each row's key stable so surviving points keep their place and focus. Set the x domain yourself to choose what the reader sees: a fixed window, the latest week, or everything so far.