Area chart
A line chart with the region under each line filled — every line-chart attribute, plus a fill opacity.
c2-area-chart
A line chart with the region under each line filled — an area chart is a line chart plus a fill, so it
extends c2-line-chart and every one of its attributes (curve, points, zoom, the axis bounds)
means the same thing here.
<c2-area-chart x-type="time" x-field="t" fill-opacity="0.2" data="[]">
<c2-chart-series field="sessions" label="Sessions"></c2-chart-series>
</c2-area-chart>
Attributes
| Name | Type | Default | Description |
|---|---|---|---|
fill-opacity | number | undefined | — | Opacity of the fill under each line. Falls back to --c2-chart__area--opacity. |
curve | 'linear' | 'smooth' | 'step' | linear | Interpolation between points. |
points | 'auto' | 'always' | 'none' | auto | When point markers are drawn. auto lets uPlot show them once points are far enough apart. |
grid | 'both' | 'x' | 'y' | 'none' | y | Which grid lines are drawn. A string rather than a boolean because a boolean attribute reads as true
whenever it is present — grid="false" in markup would turn the grid on, and there would be no way to
turn it off from HTML at all. y (the default) draws the horizontal lines, matching axes' shape. |
axes | 'both' | 'x' | 'y' | 'none' | both | Which axes are drawn. |
y-min | number | undefined | — | Lower bound of the y scale. Auto-ranged when unset. |
y-max | number | undefined | — | Upper bound of the y scale. Auto-ranged when unset. |
zoom | boolean | false | Lets the user drag horizontally to zoom the x scale. |
cursor | 'x' | 'none' | x | The cursor crosshair. |
data | ChartInput | undefined | — | The data to plot. Row objects, a bare number[], columnar [xs, ys…], or an already-normalised
frame. Compared by identity: replace the array, or bump revision after mutating it in place. |
revision | number | 0 | Bump after mutating data in place. The cheap escape hatch for a large buffer you own. |
series | ChartSeriesConfig[] | undefined | — | Series definitions, as an alternative to c2-chart-series children. Children win when both are set. |
x-field | string | — | Row field holding the x value; may be a dotted path. Defaults to the row index. |
label-field | string | — | Row field holding the category label, for charts that name their slices. |
x-type | 'time' | 'linear' | 'category' | linear | How x values are interpreted, which decides the axis and the tooltip format. |
legend | 'none' | 'top' | 'bottom' | 'start' | 'end' | bottom | Where the legend sits, or none to hide it. Shown by default: a chart with more than one series is
unreadable without one, and a single-series chart simply renders a one-entry legend. |
tooltip | 'none' | 'item' | 'axis' | axis | Whether the tooltip follows the whole x position or only the hovered datum. |
animation | 'none' | 'auto' | auto | Whether the chart animates its initial draw. ECharts uses its native shape animation and uPlot uses a
lightweight plot reveal; subsequent data updates stay immediate so a live source does not animate
every tick. Named animation rather than animate because HTMLElement.animate() is a method every
element already has, and shadowing it breaks the Web Animations API on the host. |
locale | string | undefined | — | BCP 47 locale for the axis and tooltip formatting. Defaults to the browser locale. |
loading | boolean | false | Shows the loading state instead of the plot. |
error | string | — | Shows an error message instead of the plot. |
empty-message | string | No data | Replaces the built-in "no data" text. |
max-points | number | 0 | Caps how many points a streaming chart keeps; older points fall off the front. 0 keeps everything. |
lazy-render | boolean | false | Defers loading the engine until the host first scrolls into view. |
Slots
| Name | Description |
|---|---|
default | The series definitions: c2-chart-series elements. They render nothing themselves. |
legend | Replaces the built-in legend. The built-in one is still what legend positions. |
tooltip | Replaces the built-in tooltip body. The hovered point is available through the renderTooltip property when a function is easier than markup. |
actions | Controls pinned to the top-right of the plot area, for a range picker or an export button. |
empty | Replaces the built-in "no data" message. |
loading | Replaces the built-in message shown while loading is set. |
error | Replaces the built-in message shown when error is set. |
Events
| Name | Type | Description |
|---|---|---|
tooltip-change | CustomEvent<ChartTooltipContext | null> | Fired with the complete tooltip model as the pointer moves, and with null when it leaves. Used by c2-chart-tooltip. |
series-toggle | CustomEvent<ChartSeriesToggleEventDetail> | Fired when a legend entry is toggled. Does not bubble. |
legend-change | CustomEvent<ChartLegendChangeEventDetail> | Fired when legend entries or visibility change. Used by c2-chart-legend. |
range-change | CustomEvent<ChartRangeEventDetail> | Fired after the user zooms or brushes. detail.min and detail.max are the new x bounds. Does not bubble. |
chart-ready | CustomEvent<{ engine: string }> | Fired after the engine has loaded and drawn for the first time. The host also gains data-chart-ready, which is what a test should wait on. |
chart-error | CustomEvent<{ error: unknown }> | Fired when the engine fails to load or to draw. detail.error is the underlying failure. |
point-hover | CustomEvent<ChartPointEventDetail | null> | Fired as the pointer moves between data points, and with a null detail when it leaves the plot. Does not bubble. |
point-click | CustomEvent<ChartPointEventDetail> | Fired when a datum is clicked. Does not bubble: several components fire point events, so a listener belongs on the element itself. |
CSS parts
Shadow DOM styling hooks used with ::part(name). Prefer CSS custom properties when they cover the change.
| Name | Description |
|---|---|
frame | The outer flex column holding the legend and the plot area. |
plot-area | The positioned box the engine draws into. |
plot | The engine's container element. Carries no Lit bindings, so the canvas survives every update. |
overlay | The non-interactive layer above the canvas that holds the tooltip and the actions. |
tooltip | Component-owned bubble containing the tooltip slot and its generated fallback content. |
actions | The container for the actions slot. |
state | Shared message layer containing the empty, loading, or error slot and its fallback state. |
legend | Component-owned container wrapping the legend slot and generated legend fallback. |
legend-item | One legend entry, a toggle button. |
legend-marker | The colour swatch inside a legend entry. |
CSS custom properties
Grouped by semantic target and state from --c2-component__target__state--property. Click a group to collapse it; click a name to copy it.
| Name | Type | Default | Description |
|---|---|---|---|
--c2-chart--width | length | 100% | Width of the host. The plot is absolutely positioned and has no intrinsic width, so a chart used as a flex item would otherwise collapse to its legend. |
--c2-chart--height | pixel | 320px | Height of the host. A canvas has no intrinsic size, so this is what gives the chart a box. |
--c2-chart--background | color | #ffffff | Background of the chart surface. |
--c2-chart--color | color | #18181b | Primary text colour. |
--c2-chart--font-family | font-family | inherit | Font family used for the chart chrome and the labels the engine draws. |
--c2-chart--font-size | font-size | 12px | Base font size. |
--c2-chart--padding | padding | 12px | Padding around the whole chart. |
--c2-chart--border-top | border | 1px solid #e4e4e7 | Top border. |
--c2-chart--border-right | border | 1px solid #e4e4e7 | Right border. |
--c2-chart--border-bottom | border | 1px solid #e4e4e7 | Bottom border. |
--c2-chart--border-left | border | 1px solid #e4e4e7 | Left border. |
--c2-chart--border-top-left-radius | border-radius | 8px | Top-left corner radius. |
--c2-chart--border-top-right-radius | border-radius | 8px | Top-right corner radius. |
--c2-chart--border-bottom-left-radius | border-radius | 8px | Bottom-left corner radius. |
--c2-chart--border-bottom-right-radius | border-radius | 8px | Bottom-right corner radius. |
--c2-chart__axis-line--color | color | #e4e4e7 | Colour of the axis rules uPlot draws at the plot edges. |
--c2-chart__series-1--color | color | #0265dc | Colour of the first series. |
--c2-chart__series-2--color | color | #ea580c | Colour of the second series. |
--c2-chart__series-3--color | color | #0f766e | Colour of the third series. |
--c2-chart__series-4--color | color | #db2777 | Colour of the fourth series. |
--c2-chart__series-5--color | color | #a16207 | Colour of the fifth series. |
--c2-chart__series-6--color | color | #7c3aed | Colour of the sixth series. |
--c2-chart__series-7--color | color | #0891b2 | Colour of the seventh series. |
--c2-chart__series-8--color | color | #52525b | Colour of the eighth series. Series beyond the eighth reuse the palette from the start. |
--c2-chart__line--width | pixel | 2px | Stroke width of a line series. |
--c2-chart__point--radius | pixel | 2.5px | Radius of a data point marker. |
--c2-chart__area--opacity | opacity | 0.15 | Opacity of the fill under an area series. |
--c2-chart__bar--border-radius | number | 0 | Roundedness of a bar's value end, from 0 (square) to 0.5 (fully rounded). |
--c2-chart__axis--color | color | #71717a | Colour of the axis lines and tick labels. |
--c2-chart__axis--font-size | font-size | 12px | Font size of the tick labels. |
--c2-chart__grid--color | color | #e4e4e7 | Colour of the grid lines. |
--c2-chart__grid--width | pixel | 1px | Width of the grid lines. |
--c2-chart__crosshair--color | color | #a1a1aa | Colour of the cursor crosshair. |
--c2-chart__crosshair--width | pixel | 1px | Width of the cursor crosshair. |
--c2-chart__surface--color | color | #ffffff | Surface colour handed to the engine, for marker borders and label backdrops. |
--c2-chart__muted--color | color | #71717a | Secondary text colour. |
--c2-chart__positive--color | color | #16a34a | Colour for a rising value, used by the candlestick and gauge charts. |
--c2-chart__negative--color | color | #dc2626 | Colour for a falling value, used by the candlestick and gauge charts. |
--c2-chart__legend--gap | pixel | 12px | Gap between legend entries. |
--c2-chart__legend--padding | padding | 8px 0 0 | Padding around the legend. |
--c2-chart__legend--color | color | #71717a | Legend text colour. |
--c2-chart__legend--font-size | font-size | 12px | Legend font size. |
--c2-chart__legend__disabled--opacity | opacity | 0.38 | Opacity of a legend entry whose series is hidden. |
--c2-chart__legend-marker--size | pixel | 10px | Size of the legend colour swatch. |
--c2-chart__legend-marker--border-radius | border-radius | 999px | Corner radius of the legend colour swatch. |
--c2-chart__tooltip--background-color | color | #18181b | Tooltip background. |
--c2-chart__tooltip--color | color | #fafafa | Tooltip text colour. |
--c2-chart__tooltip--font-size | font-size | 12px | Tooltip font size. |
--c2-chart__tooltip--padding | padding | 8px 10px | Tooltip padding. |
--c2-chart__tooltip--border-radius | border-radius | 6px | Tooltip corner radius. |
--c2-chart__tooltip--box-shadow | box-shadow | 0 8px 24px rgba(24, 24, 27, 0.08) | Tooltip shadow. |
--c2-chart__tooltip--gap | pixel | 6px | Gap between tooltip rows. |
--c2-chart__state--color | color | #71717a | Colour of the empty, loading and error text. |
--c2-chart__state--font-size | font-size | 14px | Font size of the empty, loading and error text. |
c2-chart-series
One series of a chart, declared as a light-DOM child. The element renders nothing: it is a definition
the chart reads, the same way c2-table reads its c2-table-column children. Everything it exposes as
an attribute can also be set as a property, and format is property-only.
<c2-line-chart x-field="month" data='[{ "month": 1, "revenue": 120, "cost": 80 }]'>
<c2-chart-series field="revenue" label="Revenue"></c2-chart-series>
<c2-chart-series field="cost" label="Cost" color="#ea580c"></c2-chart-series>
</c2-line-chart>
Attributes
| Name | Type | Default | Description |
|---|---|---|---|
field | string | — | Key of the value in the row object; may be a dotted path such as stats.cpu. |
label | string | undefined | — | Legend and tooltip label. Falls back to the field name. |
color | string | undefined | — | Explicit colour. Falls back to this series' slot in the chart's palette. |
line-width | number | undefined | — | Stroke width in pixels. Falls back to --c2-chart__line--width. |
axis | 'left' | 'right' | left | Which y axis the series is drawn against. |
span-gaps | boolean | false | Joins across gaps instead of breaking the line. |
hidden | boolean | false | Leaves the series out of the chart without removing the definition. |
c2-chart-legend
A legend linked to a chart by id. Place it anywhere in the document to control the legend's layout independently from the chart.
Attributes
| Name | Type | Default | Description |
|---|---|---|---|
for | string | — | Id of the chart this element presents. |
Slots
| Name | Description |
|---|---|
(default) | Replaces the generated legend. Use renderLegend or renderLegendItem for data-driven custom content. |
CSS parts
Shadow DOM styling hooks used with ::part(name). Prefer CSS custom properties when they cover the change.
| Name | Description |
|---|---|
item | One interactive legend entry. |
marker | The colour swatch inside an entry. |
CSS custom properties
Grouped by semantic target and state from --c2-component__target__state--property. Click a group to collapse it; click a name to copy it.
| Name | Type | Default | Description |
|---|---|---|---|
--c2-chart__legend--gap | pixel | 12px | Gap between legend entries. |
--c2-chart__legend--padding | padding | 0 | Padding around the legend. |
--c2-chart__legend--color | color | #71717a | Legend text colour. |
--c2-chart__legend--font-size | font-size | 12px | Legend font size. |
--c2-chart__legend__disabled--opacity | opacity | 0.38 | Opacity of a disabled entry. |
--c2-chart__legend-marker--size | pixel | 10px | Size of the colour swatch. |
--c2-chart__legend-marker--border-radius | border-radius | 999px | Radius of the colour swatch. |
c2-chart-tooltip
A tooltip linked to a chart by id. It can float beside the hovered point or render inline wherever it is placed in the document.
Attributes
| Name | Type | Default | Description |
|---|---|---|---|
position | 'floating' | 'inline' | floating | Whether the tooltip follows the hovered point or occupies its authored HTML position. |
placement | 'top' | 'bottom' | 'start' | 'end' | top | Preferred side of the hovered point when position="floating". Flips at viewport edges. |
for | string | — | Id of the chart this element presents. |
Slots
| Name | Description |
|---|---|
(default) | Replaces the generated tooltip body. Use renderTooltip for data-driven custom content. |
CSS parts
Shadow DOM styling hooks used with ::part(name). Prefer CSS custom properties when they cover the change.
| Name | Description |
|---|---|
bubble | The tooltip surface. |
CSS custom properties
Grouped by semantic target and state from --c2-component__target__state--property. Click a group to collapse it; click a name to copy it.
| Name | Type | Default | Description |
|---|---|---|---|
--c2-chart__tooltip--background-color | color | #18181b | Tooltip background. |
--c2-chart__tooltip--color | color | #fafafa | Tooltip text colour. |
--c2-chart__tooltip--font-size | font-size | 12px | Tooltip font size. |
--c2-chart__tooltip--padding | padding | 8px 10px | Tooltip padding. |
--c2-chart__tooltip--border-radius | border-radius | 6px | Tooltip corner radius. |
--c2-chart__tooltip--box-shadow | box-shadow | 0 8px 24px rgba(24, 24, 27, 0.08) | Tooltip shadow. |
--c2-chart__tooltip--gap | pixel | 6px | Gap between tooltip rows. |
--c2-chart__legend-marker--size | pixel | 10px | Size of the colour swatch in a tooltip row. |
--c2-chart__legend-marker--border-radius | border-radius | 999px | Corner radius of a tooltip row's colour swatch. |