HyChart

Usage examples on this page are written for Lit / plain HTML (<hy-chart>). The same component ships as HyChart in @whitespaceux/harmony-react (native React 19), with typed wrappers for Angular, Solid, Svelte, and Vue. The API reference below applies to all frameworks.

A token-themed, framework-agnostic charting component. Renders SVG directly with modular D3 (math only) inside its own shadow root, themed entirely from --hy-* design tokens.

Chart types

v1 ships a deliberately diverse set off three renderer families:

• line — continuous/time scale, path geometry (default)
• area — filled line (area + line stroke; hover still works)
• sparkline — chrome-less embedded line (no axes, points, or legend)
• bar — categorical band scale, grouped rect geometry
• pie / donut — radial arc layout (the categorical palette ring)

stacked-bar and scatter are deferred to demand.

Key Features

• Pure render/core.ts scene math → SSR-safe, deterministic, Lit↔React shared
• Series colors from the categorical ramp via category-group (the hy-avatar idiom)
• Interactive: hover readout + legend show/hide, all on the shared hit-test
• Accessible: role="img", visually-hidden data-table fallback, HC/forced-colors

Examples

Basic line chart

<hy-chart type="line" label="Revenue"></hy-chart>
<script>
document.querySelector('hy-chart').data = [
{ id: 'a', label: 'Series A', points: [{ x: 0, y: 10 }, { x: 1, y: 30 }] },
];
</script>

Bar chart (categorical x)

<hy-chart type="bar" label="Revenue by quarter"></hy-chart>
<script>
document.querySelector('hy-chart').data = [
{ id: 'rev', points: [{ x: 'Q1', y: 10 }, { x: 'Q2', y: 30 }, { x: 'Q3', y: 20 }] },
];
</script>

Donut with the legend beside the plot

The legend-position attribute (bottom default, plus end, start, top, none) controls placement; legend-marker picks the marker shape (square default, or dot). end + dot is the pie/donut convention.

<hy-chart
  type="donut"
  legend-position="end"
  legend-marker="dot"
  label="Traffic by source"
></hy-chart>

API

Properties

Property	Attribute	Type	Default	Description
type	type	'line' | 'area' | 'sparkline' | 'bar' | 'stacked-bar' | 'scatter' | 'pie' | 'donut'	'line'	The chart type: line | area | sparkline | bar | pie | donut in v1.
data	—	ChartSeries[]	[]	The data series. JS property only (arrays via hyProps), never an attribute.
options	—	ChartOptions	{}	Curated axis/display options. JS property only.
categoryGroup	category-group	string	''	Categorical group whose ramp colors the series (the hy-avatar contract).
aspectRatio	aspect-ratio	string	''	SSR dimension source, e.g. 16/9 — fixes the viewBox without measurement.
innerRadius	inner-radius	number | undefined	—	Donut hole as a fraction [0, 1) of the outer radius (pie/donut). 0 = full pie.
label	label	string	''	Accessible name for the chart (role="img" label).
legendPosition	legend-position	'top' | 'bottom' | 'start' | 'end' | 'none'	'bottom'	Where the legend sits relative to the plot: bottom (default, stacked under), end / start (beside the plot as a vertical list — the pie/donut convention), top (stacked above), or none (hidden). Layout-only; the attribute drives the placement via CSS.
legendMarker	legend-marker	'square' | 'dot'	'square'	Shape of the legend color marker: square (default, rounded square) or dot (circle — common for pie/donut). Layout-only; the attribute drives the shape via CSS.

Events

Event	Detail	Description
hover	—	Pointer over a point. Detail: { seriesId, datum } | null
select	—	A point was clicked. Detail: { seriesId, datum }
legend-toggle	—	A series was shown/hidden. Detail: { seriesId, hidden }

CSS Parts

Part	Description
base	The wrapper element
svg	The chart canvas
axis	An axis group
plot	The series-marks group
legend	The series legend

CSS Custom Properties

Property	Description
--hy-chart-series-1	Color of the first series (through --hy-chart-series-10). These 10 hooks override per-series color. Unset, every series falls back to a uniform neutral (the default foreground ink) — charts never borrow brand / feedback role colors; set category-group to apply the DS's visualization palette. The series count is NOT capped at 10 — charts with more series cycle back through the palette so every mark still paints.
--hy-chart-grid-color	Gridline color
--hy-chart-axis-color	Axis baseline color
--hy-chart-label-color	Tick/axis label color
--hy-chart-line-width	Series line thickness