Box plot
Response time by region
64 ms
Usage
Import the component and the stylesheet once. See Getting started to install the package.
import { BoxPlotCard } from '@lilt-ui/charts';
import '@lilt-ui/charts/styles.css';<BoxPlotCard
title="Response time by region"
data={regionLatency}
x="region"
samples="samples"
/>Omit title to leave out the visible title. Set header={false} to remove the whole header, and use aria-label to name a chart inside your own card. legend={false} removes the legend independently. surface="ghost" controls only the visual frame. See Card composition.
Data
Quartiles use linear interpolation. Whiskers reach the furthest sample within 1.5 times the interquartile range, and samples beyond them draw as outliers, which the axis always includes. The headline is the median of every sample pooled, not an average of medians. summarizeBox returns the same statistics, and BoxPlot draws precomputed quartiles from any series’ fields.
// One row per box with its raw samples; Lilt computes the statistics.
const regionLatency = [
{ region: 'US East', samples: [38, 44, 41, 52, 36] },
{ region: 'Europe', samples: [61, 58, 70, 66, 95] },
];Violin plot
A density silhouette reveals each delivery distribution, with measured sample dots and a median readout. Deterministic horizontal offsets separate samples without changing their values. All three loading styles share the skeleton exit, entrance, pointer/keyboard pinning, touch glide, reduced motion, and accessible readings table. Aggregate marks report null as their original datum.
import { ViolinCard } from '@lilt-ui/charts';
<ViolinCard
title="Delivery time"
data={deliverySamples}
category="carrier"
value="hours"
label="parcel"
valueFormat={{ "style": "unit", "unit": "hour", "maximumFractionDigits": 1 }}
/>| Prop | Type | Description |
|---|---|---|
title | string | Optional visible title. Omit to render no title. Also supplies the accessible name unless aria-label is set. |
header | boolean | Defaults to true. False removes the whole header: title, headline, delta and period controls, with no reserved space. Pass data directly when your app owns period selection. |
aria-label | string | Accessible chart name, independent of the visible title. Falls back to title, then a generic chart name. |
data | Row[] | One row per observation. Omit when using ranges. |
height | number | Minimum plot height, default 260. Dense lanes expand to keep every mark visible. |
depth | boolean | Lit tiles, solid bars, or spheres. Data positions remain exact; loading keeps the same depth treatment. |
color | string | Override the palette with one CSS color. |
aggregate | 'sum' | 'mean' | 'max' | Summarizes the group medians at rest. Defaults to mean. |
headline | number | Override the resting headline. |
delta | number | Fractional change shown alongside the headline. |
deltaTone | 'default' | 'inverse' | 'neutral' | Use inverse when a decrease is good. |
range | string | Static period label. |
ranges | { id, label, data, headline?, delta? }[] | Period choices with their own data. |
defaultRange | string | Initial period id. |
locale | string | Locale for numbers and dates; defaults to en-US. |
formatValue | (value: number) => string | Custom value formatter. |
badge | ReactNode | Content for the glass tab above the card. |
className | string | Class on the card frame. |
style | CSSProperties | ChartStyle | Inline styles and scoped chart variables. |
onSelectionChange | (selection | null) => void | Reports id, original row (or null for an absent day), value, and pinned state. |
renderReadout | (selection | null) => ReactNode | Consumer-owned readout, including when the header is hidden. |
valueFormat | Intl.NumberFormatOptions | Formats the headline, tiles, and axis, e.g. currency. |
surface | 'elevated' | 'outline' | 'ghost' | Card treatment. Ghost removes the visual frame only; header and legend are independent controls. |
palette | 'iris' | 'cobalt' | 'emerald' | Series colors. Iris by default; explicit series colors still win. |
numberStyle | 'count' | 'pop' | 'slide' | 'roll' | 'flow' | 'scramble' | How the headline animates when its value changes. Count (default) counts to the new value. |
loading | boolean | Shows a neutral loading skeleton, not data. |
loadingStyle | 'shimmer' | 'draw' | 'breathe' | Shimmer sweeps a highlight over still shapes; draw reveals them in order; breathe lets them settle. Follows the selected look, including depth, and respects reduced motion. |
empty | 'dots' | 'shape' | ReactElement | null | What the card shows when the period has no data. Dots (default) gathers a quiet dot field around the message; shape lays the chart’s own outline behind it. Pass `<ChartEmpty>` with your own words, any element of your own, or null for nothing. Both looks stay still, so empty never reads as loading, and the headline reads a dash, never zero. |
motion | 'auto' | 'none' | None turns off decorative motion; reduced motion does this automatically. |
legend | false | 'tiles' | 'inline' | 'list' | 'pills' | 'bars' | Legend layout; false hides it. Correlation defaults to false. |
legendSwatch | 'square' | 'dot' | 'line' | Legend marker, square by default. |
category | text key of Row | Category for each sample. |
value | numeric key of Row | Measured sample; missing samples remain in the table. |
label | text key of Row | Optional sample name. |
points | boolean | Show every sample, default true. |
bandwidth | number | Positive kernel bandwidth in measurement units; data-derived when omitted. |
scale | 'width' | 'density' | Equal maximum widths (default) or a common density scale. |
onKeyDown | KeyboardEventHandler<HTMLElement> | Keyboard handler on the card frame. Chart inspection also has its own keyboard handling. |
Props
Every prop BoxPlotCard accepts, in the order you are likely to reach for them.
| Prop | Type | Description |
|---|---|---|
title | string | Optional visible title. Omit to render no title. Also supplies the accessible name unless aria-label is set. |
data | Row[] | One row per x position. Omit when using ranges. |
x | key of Row | Text, number, or Date field for the x axis. |
samples | key of Row | Field holding each row’s raw samples, as a number array. |
label | string | Names the series in hover. Defaults to Median. |
color | string | Any CSS color. |
outliers | boolean | Draw samples beyond the whiskers as dots. Defaults to true. |
depth | boolean | Draws each box as a solid block centered on its group, with whiskers through its middle and the median wrapped around it. |
header | boolean | Defaults to true. False removes the whole header: title, headline, delta and period controls, with no reserved space. Pass data directly when your app owns period selection. |
aria-label | string | Accessible chart name, independent of the visible title. Falls back to title, then a generic chart name. |
delta | number | Fractional change for the chip: 0.082 shows +8.2%. |
deltaTone | 'default' | 'inverse' | 'neutral' | Use inverse when a decrease is good. |
headline | number | Resting headline. Defaults to the aggregate of non-reference series; dashed series are excluded. |
range | string | Static period label in the header. |
valueFormat | Intl.NumberFormatOptions | Formats the headline, tiles, and axis, e.g. currency. |
legend | false | 'tiles' | 'inline' | 'list' | 'pills' | 'bars' | False removes the legend without changing the data. How the legend under the plot lays out: value tiles (default), a compact inline key, list rows, tinted pills, or bars that also draw each value against the largest. |
legendSwatch | 'square' | 'dot' | 'line' | The mark beside each legend label. Defaults to a rounded square. |
height | number | Plot height in pixels. Defaults to 240. |
axis | 'minimal' | 'dots' | 'inline' | 'ruler' | 'classic' | 'segmented' | { x, y } | Axis preset. Minimal (default) labels only the x ends and has no grid. Set one per axis with `{ x, y }`; a segmented axis can take a `gradient` to read as a range. |
hover | 'pills' | 'tooltip' | 'strip' | 'headline' | The one readout for the hovered point: pills on the axes (default), a tooltip with every series, a strip docked above the plot, or the headline and tiles alone. |
hoverStyle | 'soft' | 'solid' | 'accent' | How the pills or tooltip look. Soft (default) is surface glass; accent tints it with the hovered series. |
pillPosition | 'auto' | 'mark' | 'axis' | Where the value pill sits: above the hovered mark, or on the y axis. Auto picks mark when there are no y labels. |
tooltipIndicator | 'square' | 'dot' | 'line' | Series marker on each tooltip row, with hover="tooltip". Square by default. |
background | 'dots' | 'grid' | 'lines' | 'none' | Texture behind the marks. Dots by default, with a hover spotlight. |
surface | 'elevated' | 'outline' | 'ghost' | Card treatment. Ghost removes the visual frame only; header and legend are independent controls. |
palette | 'iris' | 'cobalt' | 'emerald' | Series colors. Iris by default; explicit series colors still win. |
axisInset | number | Padding between the plot edges and axis labels or pills. |
loading | boolean | Shows a neutral loading skeleton, not data. |
loadingStyle | 'shimmer' | 'draw' | 'breathe' | Shimmer sweeps a highlight over still shapes; draw reveals them in order; breathe lets them settle. Follows the selected look, including depth, and respects reduced motion. |
empty | 'dots' | 'shape' | ReactElement | null | What the card shows when the period has no data. Dots (default) gathers a quiet dot field around the message; shape lays the chart’s own outline behind it. Pass `<ChartEmpty>` with your own words, any element of your own, or null for nothing. Both looks stay still, so empty never reads as loading, and the headline reads a dash, never zero. |
compare | boolean | 'headline' | 'badge' | Drag across the plot to compare two points in time. True or headline reads the change in the headline; badge reads it in the card’s tab and leaves the headline at rest. |
sync | string | Link hover and pins with every card that uses the same name, matched by x value. A click pins them all, with a ghost pin on the others; Alt-click pins one card only. |
numberStyle | 'count' | 'pop' | 'slide' | 'roll' | 'flow' | 'scramble' | How the headline animates when its value changes. Count (default) counts to the new value. |
motion | 'auto' | 'none' | None turns off decorative motion; reduced motion does this automatically. |
defaultRange | string | Initial range id; defaults to the first supplied range. |
locale | string | Locale used for number formatting. Defaults to en-US. |
formatValue | (value: number) => string | Custom value text, taking precedence over valueFormat. |
formatAxisValue | (value: number) => string | Custom compact axis value text. |
formatX | (value: string | number | Date) => string | Custom x label text. |
xType | 'category' | 'number' | 'time' | Override inferred x type. Use time for numeric Unix timestamps in milliseconds. |
spotlight | boolean | Highlight the inspected position in the plot background. Defaults to true. |
badge | ReactNode | Content in the tab above the card. A comparison badge can replace this while a comparison is active. |
className | string | Additional class on the card frame. |
style | CSSProperties | ChartStyle | Inline styles and scoped --lilt-* chart variables. |
pillValue | 'series' | 'stack' | Read an individual series value (default) or its stacked height. Has no effect when the card has no stacked series. |
decimate | boolean | Defaults to true. Line and Area marks retain at most four observations per pixel column. Other marks draw every row; inspection and summaries always read the full data. |