Overview
Reference usage
Compact labeled meter with a thin horizontal fill bar for inline cost, token, budget, or quota breakdowns. Given points, it draws the shape of a metric over a window instead: a thin line over a baseline with a dot on the latest value.
Usage
Trend line
Pass points (oldest first) to draw a line instead of a bar. startLabel and endLabel name the two ends of the window. The line is an image: label is its whole accessible name (a sentence such as "Storage use over the last 24 hours, rising to 1.6 GB") and is not drawn, because the card around it carries the visible title.
The line and its end dot are the accent colour (the first theme.palette entry overrides it). The scale runs from the series' lowest to its highest value, so the line shows shape and not magnitude; put the figure in the card. A series with fewer than two finite values draws only the baseline.
Theming
Sparkbar inherits its foreground from currentColor and keeps its background transparent. The default accent fill uses the first resolved --cinder-chart-series-* color, and a partial theme can override that palette. The success and warning variants keep their semantic status tokens; the meter's filled position communicates magnitude independently of color.
When to use
- Comparing several bounded values in dense rows, such as per-step spend, token usage, or budget consumption.
- Showing the shape of one metric over a recent window inside a metric card, with its latest value marked and the window named at each end.
- Showing task completion or loading progress. Use Progress instead
- Rendering a full cartesian chart with axes, scales, or multiple series. Use Line Chart instead
Examples
Basic sparkbars
Compact bounded meters for inline spend and usage rows.
Custom range
Use a max value when the measurement is not fractional.
Trend line
Pass points to draw the shape of a metric over a window: a thin line over a baseline, a dot on the latest value, and a label at each end. The label is the accessible name and is not drawn.
Props
Name | Type | Default | Description |
|---|---|---|---|
value | discriminated-union | Current bounded value. | |
max | discriminated-union | 1 | Upper bound for the range. Defaults to 1 for fractional values. |
label required | text | Visible label for the measured row. | |
trailing | discriminated-union | Optional trailing value such as a cost, token count, or percentage. | |
points | discriminated-union | ||
startLabel | discriminated-union | ||
endLabel | discriminated-union | ||
size | 'sm' | 'md' | 'lg' | 'md' | Track thickness and text scale. Default md. For a line, the height of the plot: 3rem, 6rem or 8rem. |
variant | discriminated-union | 'accent' | Fill color intent. Default accent. |
theme | ChartTheme | Partial visual theme override. Omitted fields inherit the surrounding application. | |
ariaLabel | text | Accessible name override. Defaults to ${label}, ${percentage}% for a bar, and to label for a line. | |
ariaValueText | discriminated-union | Accessible value text override. Defaults to the trimmed trailing value when provided. |