Chart

Chart

A single component, two engines, one data shape.

Engine	Canvas / SVG	Bundle	Strengths
chartjs (default)	Canvas (chart.js/auto)	~70 KB gz	Battle-tested. Good for dense data. Mobile-friendly tooltips.
recharts	SVG	~110 KB gz	Pure React. Easy to compose with helixui surfaces (e.g. cards).

# Chart.js
pnpm add chart.js

# Recharts
pnpm add recharts

The base @helixui/core bundle does not pull either until a <Chart> mounts.

Unified data shape

const data: ChartData = {
  labels: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'],
  datasets: [
    { label: 'Sessions',   data: [120, 200, 150, 280, 240], color: 'brand' },
    { label: 'Conversions', data: [12, 24, 18, 36, 30],     color: 'success' },
  ],
};

Per-dataset color accepts:

• a helixui scale ref — 'brand' | 'success' | 'warning' | 'danger' | 'neutral'
• a CSS variable — '--helixui-color-bg-action-brand-default'
• a CSS color — '#ff6680', 'oklch(0.62 0.18 264)'

If no color is given, the dataset gets a slot from helixui’s categorical scale.

Examples

<Chart type="line"     data={data} />
<Chart type="area"     data={data} smooth />
<Chart type="bar"      data={data} />
<Chart type="stackedBar" data={data} />
<Chart type="doughnut" data={{ labels: ['A','B','C'], datasets: [{ label: 'mix', data: [3, 5, 2] }] }} cutout={0.65} />
<Chart type="radar"    data={data} />
<Chart type="scatter"  data={data} />

Switch engines with the engine prop:

<Chart engine="recharts" type="area" data={data} />

Theming

theme="auto" watches document.documentElement.dataset.theme. Tick / grid / legend colors swap on the next render — no remount.

Compact widgets

Combine with <StatCard> for KPI tiles:

<StatCard label="Revenue" value="$24,580" delta="+8.2%">
  <Chart type="area" data={trend} hideAxes legend={false} grid={false} height={64} />
</StatCard>

For tiny inline trends, prefer <Sparkline> — it is dependency-free SVG.

Escape hatches

<Chart
  engine="chartjs"
  type="line"
  data={data}
  chartjsOptions={{
    scales: { y: { suggestedMin: 0, suggestedMax: 100 } },
    plugins: { tooltip: { intersect: false, mode: 'index' } },
  }}
/>

Install: @helixui/core

import { Chart } from '@helixui/core'

status: stable · since: 0.7.0

Tags: data-viz, graph, plot, analytics

Anatomy

┌──────────────────────────────┐
│  Title                        │
│  ▁▂▃▅▆▇█▇▆▅▃▂▁  legend       │
│  └──────────────axis────────  │
│  Caption                      │
└──────────────────────────────┘

Layout

• display — block
• width — fill
• height — fixed:320px
• intrinsicSize — fills available width, default 320px tall
• stackable — true
• fullBleed — false

Visual

A surface with optional title, legend, and caption. The plot area uses brand / success / warning / danger token colors for series. Tooltips appear on hover/touch; axis labels use muted text. Animations respect prefers-reduced-motion.

Props

Name	Type	Default	Description
type	'line' | 'area' | 'bar' | 'stackedBar' | 'horizontalBar' | 'pie' | 'doughnut' | 'radar' | 'scatter'	—	Chart type. Same set across both engines.
data	ChartData	—	Unified { labels, datasets } shape. Adapters translate it.
engine	'chartjs' | 'recharts'	chartjs	Which engine to use. Chart.js draws to canvas; Recharts to SVG.
theme	'light' | 'dark' | 'auto'	auto	auto follows document.documentElement.dataset.theme.
legend	boolean	true	Show / hide the legend.
grid	boolean	true	Show / hide axis grid lines.
tooltip	boolean	true	Show / hide tooltips on hover/touch.
animate	boolean	auto	Animate on mount and on data change. Defaults follow prefers-reduced-motion.
hideAxes	boolean	false	Useful for compact widgets — drops both x and y tick labels.
smooth	boolean	true	Smoothed curves for line/area.
compactNumbers	boolean	true	Pretty-format the y-axis as 1.2K / 3.4M.
cutout	number	0.6	Doughnut cutout (0–1). Ignored for non-doughnut types.
height	number | string	320	Numbers are treated as px.
title	ReactNode	—	Optional title rendered above the chart.
caption	ReactNode	—	Optional caption rendered below the chart.
chartjsOptions	Record<string, unknown>	{}	Spread last into Chart.js options. Escape hatch.
rechartsOptions	Record<string, unknown>	{}	Reserved for the recharts adapter.
onMount	(info: { engine, instance }) => void	—	Fires once mounted. Receives the underlying engine instance.

Tokens used

color.bg.surface.default, color.bg.surface.subtle, color.bg.action.brand.default, color.bg.action.success.default, color.bg.action.warning.default, color.bg.action.danger.default, color.bg.action.danger.subtle, color.border.default, color.text.primary, color.text.muted, color.text.action.danger, radius.md, font.family.sans, motion.duration.fast, motion.easing.standard

Accessibility

Notes

• Canvas-based engines (Chart.js) get a role='img' on the canvas with the chart title as aria-label.
• Tooltips honor pointer + touch.
• Animations turn off when prefers-reduced-motion: reduce unless animate is explicitly set.

Composes with

Component	Relation	Note
Card	parent	Often wrapped in a Card on dashboards.
StatCard	sibling	KPI tiles next to a chart.
Sparkline	alternative	Use Sparkline for tiny inline trends.

Prompt examples

These are the AI prompt → JSX mappings used by the helixui prompt DSL and integrations like Cursor / Claude Code.

monthly revenue line chart

“show a line chart of revenue”

<Chart type="line" data={{ labels, datasets: [{ label: 'Revenue', data }] }} />

bar chart with engine override

“use recharts for a bar chart”

<Chart engine="recharts" type="bar" data={data} />

Related

• Sparkline
• StatCard