useChart

Create a theme-aware chart instance from your data and series.

useChart is the single hook for every chart in @saas-ui/charts. It stores the data, resolves Chakra tokens, and returns helpers used by Chart.Root, BarList and BarSegment.

import { useChart } from '@saas-ui/charts'

const chart = useChart({
  data,
  series: [{ name: 'revenue', label: 'Revenue', color: 'indigo.solid' }],
})

Options

Prop	Type	Description
`data`	`T[]`	Rows the marks and compositions read from.
`series`	`SeriesItem<T>[]`	Named series for color, label, icon and tooltip matching.
`sort`	`{ by, direction }`	Sort a copy of `data` by a numeric field.

Series

interface SeriesItem<T> {
  name?: keyof T | string
  color?: ChartColor
  icon?: React.ReactNode
  label?: React.ReactNode
}

name is matched against mark and tooltip payloads. color accepts a token path (indigo.solid) or any CSS color. When series omit colors, useChart falls back to indigo.solid, pink.solid, teal.solid, orange.solid, purple.solid and fg.

Return value

Data

data — the original rows, or a sorted copy when sort is set
series — the series you passed in
groupBy(dataKey) — group rows by a field
getSeries(item) — resolve the series for a tooltip point or datum
getTotal(dataKey), getMin(dataKey), getMax(dataKey)
getValuePercent(dataKey, value, domain?) — percent of the total, or of a custom [min, max] domain
getPayloadTotal(payload) — sum tooltip point values

Tokens

color(token), size(token), spacing(token) — resolve theme tokens
theme — TanStack theme (foreground, muted, grid, background, palette)
palette — resolved series colors, used by pie and categorical scales
cssVars — CSS variables applied by Chart.Root for tooltip chrome and series colors
gradient({ id, stops }) — build a linear gradient with token colors

Definition

chart.define(spec) wraps TanStack's defineChart. It injects the theme, disables SVG animation by default, and portals tooltips so they are not clipped by overflow.

const definition = chart.define({
  marks: [
    barY(chart.data, {
      x: 'date',
      y: 'revenue',
      fill: chart.color('indigo.solid'),
    }),
  ],
  x: { scale: () => scaleBand<string>().padding(0.28) },
  y: { scale: scaleLinear, nice: true, grid: true },
})

Pass any TanStack chart spec: marks, scales, axes, color, margin, gradients or a responsive chart({ width }) builder. See chart definitions in the TanStack docs.

Formatting

formatNumber(options?) — Intl.NumberFormat bound to the Chakra locale
formatDate(options?) — Intl.DateTimeFormat bound to the Chakra locale

Highlighting

highlightedSeries / setHighlightedSeries(name)
isHighlightedSeries(name)
getSeriesOpacity(name, fallback?) — 1 for the highlighted series, fallback (default 0.2) for the others

Chart.Legend uses these to dim sibling series on hover or click. HTML compositions such as BarList and BarSegment use the same state for tooltips.

Desktop

Mobile

'use client'

import { Chart, useChart } from '@saas-ui/charts'
import { lineY } from '@tanstack/charts'
import { scaleBand } from '@tanstack/charts/scales/band'
import { scaleLinear } from '@tanstack/charts/scales/linear'
import { useMemo } from 'react'

const data = [
  { date: 'Jan', desktop: 820, mobile: 420 },
  { date: 'Feb', desktop: 910, mobile: 670 },
  { date: 'Mar', desktop: 880, mobile: 610 },
  { date: 'Apr', desktop: 1040, mobile: 780 },
  { date: 'May', desktop: 980, mobile: 780 },
  { date: 'Jun', desktop: 1120, mobile: 990 },
]

export const ChartLineMultiple = () => {
  const chart = useChart({
    data,
    series: [
      { name: 'desktop', label: 'Desktop', color: 'indigo.solid' },
      { name: 'mobile', label: 'Mobile', color: 'pink.solid' },
    ],
  })

  const definition = useMemo(
    () =>
      chart.define({
        marks: [
          lineY(chart.data, {
            x: 'date',
            y: 'desktop',
            stroke: chart.color('indigo.solid'),
            strokeWidth: 2,
            points: true,
          }),
          lineY(chart.data, {
            x: 'date',
            y: 'mobile',
            stroke: chart.color('pink.solid'),
            strokeWidth: 2,
            points: true,
          }),
        ],
        x: {
          scale: () => scaleBand<string>().padding(0.12),
          grid: false,
          axis: { line: false, ticks: { size: 0 } },
        },
        y: {
          scale: scaleLinear,
          nice: true,
          grid: true,
          axis: { line: false, ticks: { size: 0 } },
        },
      }),
    [chart],
  )

  return (
    <Chart.Root
      chart={chart}
      definition={definition}
      height={240}
      ariaLabel="Sessions by device"
    >
      <Chart.Legend />
    </Chart.Root>
  )
}

Introduction

Chart