`<dj-chart>`

A themeable, accessible SVG chart.

Set data (an array of rows) and series. The chart is built on D3's scales and shapes, but the SVG is real DOM owned by the component, so you can theme it with --dj-* tokens and ::part(), and assistive technology can read it. It is not a form control.

Try it in the playground

@dojo-ng/chart · v0.2.1 · The same package also registers <dj-sparkline>.

npm install @dojo-ng/chart

import "@dojo-ng/chart";

Chart types

type selects the mark:

Cartesian (line, area, bar) reads category-key for the x axis.
X/Y (scatter, bubble) reads x-key for a numeric x, and size-key for the bubble radius.
Radial (pie, donut) draws one series as slices by category.
stacked stacks bars and areas. A series can override type to make a combination chart.

Interaction

legend-toggle lets users show and hide a series from its legend item.
brush adds an overview strip below a cartesian chart for choosing the visible range of categories. Double-click the strip to reset it.

Live data

appendData() adds rows without rebuilding the data array, for cheap live updates. max-points limits how many rows it keeps.

Sizing

The chart fills its container's width and takes its height from --dj-chart-height (default 18rem). Set that property to resize it.
A fixed height on a wrapper element does not limit the chart, and a wrapper shorter than the chart lets the legend overflow. The legend sits below the plot, inside that height.

Accessibility

A visually hidden data table is the accessible equivalent of the chart.
The chart has role="img" and a generated summary.
Animation follows prefers-reduced-motion.
The series colors are the --dj-chart-1 to --dj-chart-8 tokens.

Plugins

Add features to <dj-chart> by installing a plugin package and adding it to the plugins property. To build your own, see Writing plugins.

chart-financialCandlestick, volume, and indicator plugins (OHLC support package, no custom element)

Properties

Property	Attribute	Type	Default
`data`	Property only	`ChartDatum[]`	`[]`
`series`	Property only	`ChartSeries[]`	`[]`
`categoryKey`	`category-key`	`string`	`""`
`type`	`type` reflected	`"line""area""bar""scatter""bubble""pie""donut"`	`"line"`
`orientation`Bar orientation. `"horizontal"` puts categories on the Y axis and values on the X axis; it applies only to `bar` charts and ignores `brush` and a secondary (right) axis (v1).	`orientation` reflected	`"vertical""horizontal"`	`"vertical"`
`stacked`	`stacked`	`boolean`	`false`
`showLegend`	`show-legend`	`boolean`	`true`
`showGrid`	`show-grid`	`boolean`	`true`
`xLabel`	`x-label`	`string`	None
`yLabel`	`y-label`	`string`	None
`yLabelRight`Title for the secondary (right) y-axis, shown when a series sets `axis: "right"`.	`y-label-right`	`string`	None
`label`Accessible-name lead-in; the generated data summary is appended.	`label`	`string`	None
`markers`Show point markers at each datum on line and area series.	`markers`	`boolean`	`false`
`xKey`Numeric x accessor for scatter/bubble charts.	`x-key`	`string`	`""`
`sizeKey`Numeric accessor for bubble radius (area-encoded).	`size-key`	`string`	None
`innerRadius`Donut/pie hole size as a fraction of the radius (0 = pie); donut defaults to 0.6.	`inner-radius`	`number`	None
`centerLabel`Text centered in a donut hole (ignored for other types). Also appended to the aria-label.	`center-label`	`string`	None
`centerSubLabel`Smaller text below the donut center label.	`center-sub-label`	`string`	None
`legendToggle`Make legend items toggle series visibility (cartesian and x/y charts).	`legend-toggle`	`boolean`	`false`
`brush`Show a brush strip below cartesian charts to select the visible category window.	`brush`	`boolean`	`false`
`numberFormat`Intl number-format options for y-axis ticks and tooltip values (locale-aware).	Property only	`Intl.NumberFormatOptions`	None
`formatY`Override y value formatting; takes precedence over numberFormat and the locale.	Property only	`(value: number) => string`	None
`formatX`Override x category-label formatting.	Property only	`(category: string) => string`	None
`maxPoints`Cap on `data` rows kept after `appendData` appends; 0 (default) is unbounded. Old rows are trimmed from the front, so the chart shows a sliding window of the most recent data.	`max-points`	`number`	`0`
`renderer`Opt-in escape hatch for very large series: `"canvas"` draws series marks on a `<canvas>` instead of SVG nodes (axes, grid, legend, and tooltip stay SVG/DOM either way). Honored only for `line`/`area`/`scatter` (not `bar`, `stacked`, pie/donut, `bubble`, or a combo where any series overrides to `bar`) and only outside `forced-colors: active`; unsupported combinations fall back to `svg` (a console warning for an unsupported type, none for forced-colors).	`renderer` reflected	`"svg""canvas"`	`"svg"`
`missing`How a missing (non-finite) cell is drawn. `"gap"` (the default) breaks the line/area and omits the marker, bar, and point — the honest reading, since the alternative silently plots a zero the data never gave. `"connect"` spans the hole in a line/area instead of breaking it (bars, markers, and points are still omitted). `"zero"` treats it as a real zero — the behavior before `missing` existed, kept as an escape hatch. Per-series override on `ChartSeries.missing`.	`missing` reflected	`"gap""connect""zero"`	`"gap"`
`pointLabels`Show a label at each plotted point/bar/slice (line, area, scatter, bar, pie/donut — not horizontal bars). Per-series override on `ChartSeries.pointLabels`. No label is drawn for a gap; above ~150 candidates the whole set is skipped (a console warning once) rather than drawing an unreadable smear of overlapping numbers.	`point-labels`	`boolean`	`false`
`formatPoint`Override point-label text; defaults to `fmtY(value)` (so `numberFormat`/`formatY` apply with no extra wiring). Receives the row and the series, so a label can show something the plotted number alone can't — a name from another column, a share of total. When set, `renderTable` mirrors the SAME formatted text into the affected cells too, since otherwise it would be sighted-only information no screen reader can reach.	Property only	`(value: number, row: ChartDatum, series: ChartSeries) => string`	None
`yScale`The value axis's scale — names the VALUE axis regardless of `orientation` (so it drives horizontal bars' x-axis too), matching the existing `yLabel`/`fmtY` convention. `"log"` never includes zero: a non-positive value has no position on it and is always a gap, even under `missing="zero"`. Refused together with `stacked` (a stacked segment's drawn height on a log axis is a ratio, not a quantity) — falls back to `"linear"` with a console warning.	`y-scale` reflected	`"linear""log"`	`"linear"`
`yScaleRight`Same as `yScale`, for the secondary (right) axis — so a price-on-log with volume-on-linear combo works.	`y-scale-right` reflected	`"linear""log"`	`"linear"`
`plugins`Plugins draw extra marks (candlesticks, volume, an indicator) without the core knowing anything about them — factories, not classes, no registry. Applies to the vertical cartesian family only (line/area/bar, not stacked-plus-anything-else here beyond what cartesian already means, and not xy/radial/horizontal). A `plugins` change disposes every previous plugin's `setup()` and runs the new array's, in an ordinary reactive update (there is no creation-time constraint to guard, unlike `rich-text`/`data-grid`'s plugin seams). Forces `renderer="svg"`: mixing a canvas mark layer with plugin-drawn SVG would need a second draw protocol nobody has asked for. Default `[]` — a chart with no plugins renders exactly as one with the property absent.	Property only	`ChartPlugin[]` Plugins	`[]`

Events

Event	Description
`dj-legend-toggle`	detail `{ key, hidden }`
`dj-hover`	detail `{ category }` or `null`; cartesian and radial

CSS parts

Style these with dj-chart::part(name).

plotaxisgridseriesbarlinepointslicelegendlegend-itembrush-handletooltipplot-canvascenter-labelcenter-sub-labelpoint-labelspoint-label

CSS custom properties

Property	Default	Description
`--dj-chart-height`	`18rem`	Overall chart height (width fills the container).
`--dj-chart-label-size`	`0.6875rem`	Point-label font size.
`--dj-chart-label-color`	None	Point-label text color; defaults to `--dj-color-text`.
`--dj-chart-label-halo`	None	Point-label halo stroke; defaults to `--dj-color-background`.
`--dj-chart-1`	`#2563eb`	Categorical series color 1.
`--dj-chart-2`	`#16a34a`	Categorical series color 2.
`--dj-chart-3`	`#d97706`	Categorical series color 3.
`--dj-chart-4`	`#dc2626`	Categorical series color 4.
`--dj-chart-5`	`#7c3aed`	Categorical series color 5.
`--dj-chart-6`	`#0891b2`	Categorical series color 6.
`--dj-chart-7`	`#db2777`	Categorical series color 7.
`--dj-chart-8`	`#65a30d`	Categorical series color 8.

Methods

Method	Description
`appendData(rows: ChartDatum[])`	Append rows without rebuilding `data` yourself: cheap live updates for streaming sources. Multiple calls within the same animation frame coalesce into a single `data` assignment. Trims from the front to `max-points` when set, and clears an active brush selection (its indices are into the pre-append data and would otherwise point at the wrong window).
`toSvg(): string`	Serializes the current plot as a standalone SVG string: presentational styles inlined (no external stylesheet or theme tokens needed to render it correctly elsewhere) and, when the canvas renderer is actually in effect (`effectiveRendererNow`, never the raw `renderer` property — they differ whenever a fallback applies, and a chart that asked for canvas but fell back must not get an empty bitmap composited over it), its drawn bitmap composited in at the same position and stacking it renders on screen. `""` when the chart isn't `ready` (no data, zero measured size) — the same gate `render()` uses for its placeholder.
`toPng(scale): Promise<Blob>`	Rasterizes `toSvg`'s output to a PNG `Blob` at `scale`× (default 2, for retina and for print). Rejects if the chart isn't `ready` (`toSvg` would return `""`).

Types

The types that the properties above use, as they are declared in the source.

`ChartDatum`

export type ChartDatum = Record<string, unknown>;

`ChartSeries`

export interface ChartSeries {
  /** Accessor key into each data row for this series' numeric value. */
  key: string;
  /** Legend and data-table label; defaults to `key`. */
  label?: string;
  /** Per-series mark type; defaults to the chart's `type`. */
  type?: ChartType;
  /** Explicit color; otherwise assigned from the theme ramp by index. */
  color?: string;
  /** Per-series numeric x accessor for scatter/bubble; defaults to the chart's `xKey`. */
  xKey?: string;
  /** Numeric accessor for bubble radius (area-encoded); defaults to the chart's `sizeKey`. */
  sizeKey?: string;
  /** Which y-axis this series uses. `"right"` adds a secondary axis with its own scale. Defaults to `"left"`. */
  axis?: "left" | "right";
  /** Override the chart's `missing` handling for this series. */
  missing?: MissingMode;
  /** Override the chart's `pointLabels` for this series. */
  pointLabels?: boolean;
}