Skip to content

shadcn.io is an independent project built on shadcn/ui

Free

ECDF chart

The share of values at or below any point, with no bin size to pick. Read medians and percentiles straight off the curve, and compare samples on one chart.

Charting library: TanStack Charts

Preview

Preview width

Installation

The command adds the example above to components/charts/ and, the first time, the chart kit to components/ui/charts/. Both are source files in your project from then on: read them, change them, delete what you don't use.

Sign in to get your install command
Free with an account. It carries your token, so the CLI installs everything in one go.
GoogleGitHub
Use email insteadNo credit card

Usage

Rows are raw observations, as for a histogram. Each Ecdf sorts its column and steps up at every value it finds.

import {
  Ecdf,
  EcdfChart,
  EcdfTooltip,
  EcdfXAxis,
  EcdfYAxis,
  Grid,
} from "@/components/ui/charts";

// One row per request, in milliseconds.
const data = [
  { ms: 182 }, { ms: 240 }, { ms: 198 }, { ms: 311 }, { ms: 205 },
  { ms: 264 }, { ms: 189 }, { ms: 422 }, { ms: 231 }, { ms: 217 },
  { ms: 176 }, { ms: 293 }, { ms: 208 }, { ms: 356 }, { ms: 221 },
];

const formatMs = (value: number) => `${value} ms`;

export const ResponseTimeChart = () => (
  <EcdfChart ariaLabel="Checkout response times" data={data} percentiles={[0.5, 0.9]}>
    <Grid horizontal />
    <Ecdf dataKey="ms" label="Requests" showArea />
    <EcdfXAxis formatValue={formatMs} />
    <EcdfYAxis />
    <EcdfTooltip />
  </EcdfChart>
);

Anatomy

Each Ecdf is one step line. The y axis always runs from 0 to 100% of a series' rows.

<EcdfChart data={data} percentiles={[0.5, 0.9]}>
  <Grid horizontal />
  <Ecdf dataKey="before" label="Before" stroke="var(--chart-3)" />
  <Ecdf dataKey="after" label="After" stroke="var(--chart-1)" />
  <EcdfXAxis />
  <EcdfYAxis />
  <EcdfTooltip />
</EcdfChart>
  • EcdfChart: Sorts each series, sets the value axis and draws the percentiles guides.
  • Grid: Guide lines, horizontal by default.
  • Ecdf: One series as a step line, with showArea for a soft fill under it.
  • EcdfXAxis: The values along the bottom.
  • EcdfYAxis: The share, as a percentage unless you pass formatValue.
  • EcdfTooltip: Each series' share at or below the hovered value.

Percentile guides

Pass fractions to percentiles, such as [0.5, 0.9], for dashed guides across the plot labeled p50 and p90. Where a line crosses a guide, read down to the axis for that series' percentile.

Comparing series

Add an Ecdf per series. At any share, the horizontal gap between two lines is how far apart they are at that percentile, so the faster release is the line further left.

Hovering shows a crosshair with a dot where it meets each line, and the tooltip lists every series' share at that value.

Preview width

Customization

The kit is in your project, in components/ui/charts/: your framework's components over a shared core/. Change a default there and every chart picks it up.

className goes on the chart's container, so size and spacing are utility classes.

The tooltip's content gets the hovered value and a series array with each one's share, count and total. That's enough to say "212 of 240 requests" instead of a percentage.

strokeWidth on an Ecdf sets the line (2 px). Pass domain to keep the value axis the same across charts. Values outside it end the line at the edge.

<EcdfTooltip
  content={({ point }) => (
    <TooltipContent
      rows={point.series.map((series) => ({
        color: series.color,
        label: series.label,
        value: `${series.count} of ${series.total}`,
      }))}
      title={`Within ${point.value} ms`}
    />
  )}
/>

Where a part renders content of its own, you pass it in. In React:

  • EcdfTooltip: content={({ point, index }) => …}

Loading state

While status is "loading", each series draws a skeleton staircase and the pointer is ignored. loadingLabel adds text over it. On "ready" the real lines draw in from the left.

<EcdfChartLoading /> is the placeholder for a chart that has no rows yet.

Preview width

Animation

The lines draw in from left to right over animationDuration (1100 ms), every series at once. animate={false} on an Ecdf shows it whole from the first frame.

When the data changes, the steps glide to their new shares over 500 ms. Reduced motion skips the entrance and the glide.

Theming

Every color in the kit is one of your theme's tokens or a mix of them, except --chart-positive, a fixed green. A preset or the .dark class restyles the chart, and overriding a token in your CSS changes it everywhere.

An Ecdf takes its color as stroke, and showArea fills under it at 10% of that color. The percentile guides use --chart-crosshair and their labels --chart-label.

TokenDefaultPaints
--chart-1your theme'sthe first series
--chart-3your theme'sthe third series
--chart-crosshair--muted-foreground at 75%the hover line
--chart-background--carddot halos, the gaps between stacked marks
--chart-grid--bordergrid lines
--chart-label--muted-foregroundtick labels
--chart-tooltip-background--popoverthe tooltip panel
globals.css
:root {
  --chart-crosshair: var(--primary);
  --chart-background: var(--background);
}

Accessibility

The chart is an image named by ariaLabel ("ECDF chart" by default). The keyboard steps through every distinct value, which can be hundreds of stops, so state the percentiles that matter in ariaDescription.

Tab
Moves focus to the chart and shows the smallest value.
Arrow Right
Moves to the next observed value. ArrowDown does the same.
Arrow Left
Moves to the previous value. ArrowUp does the same.
Home
Jumps to the smallest value.
End
Jumps to the largest value.

API reference

EcdfChart

PropType
domain?readonly [number, number]

The value axis range [min, max]. Defaults to the observations' extent, rounded to nice values.

percentiles?readonly number[]

Shares to mark with a dashed guide across the plot and its label, as fractions: [0.5, 0.9] marks the median and the 90th percentile.

datareadonly DistributionRow[]

The observations, one object per row. Each series reads its dataKey column; rows without a finite number there are skipped.

aspectRatio?string

Width to height ratio of the chart, for example "2 / 1" or "16 / 9".

Default
"2 / 1"
margin?Partial<ChartMargin>

Space around the plot in pixels, per side. Each side defaults to fit the chart's axes.

Type
Partial<ChartMargin>
animationDuration?number

Duration of the entrance in milliseconds.

Default
1100
ariaLabel?string

Accessible name of the chart. Defaults to its kind, for example "Histogram" or "Box plot".

ariaDescription?string

Accessible description of the chart.

status?ChartStatus

"loading" draws a shimmering skeleton shaped like the chart in place of its marks and ignores the pointer; switching to "ready" plays the entrance. Switching back to "loading" fades the marks out first.

Default
"ready"
loadingLabel?string

Text shown centered over the plot, with a shimmer, while status is "loading". Nothing is shown when it is unset or empty.

className?string

Class names added to the chart's container.

style?CSSProperties

Inline styles for the chart's container.

children?ReactNode

The chart's parts: its series, Grid, axes and tooltip.

Ecdf

PropType
strokeWidth?number

Width of the step line in pixels.

Default
2
showArea?boolean

Fill the area under the steps with a soft wash of the series colour.

Default
false
dataKeystring

Key of the numeric column this series reads from each row.

label?string

The series' name in the tooltip and legend. Defaults to dataKey.

fill?string

Fill colour. Defaults to the series' palette colour, var(--chart-1) for the first.

stroke?string

Outline colour. Defaults to the fill.

fadedOpacity?number

Opacity of the other items while one is hovered (and of the other series while a legend row is).

Default
0.3
animate?boolean

Play the entrance.

Default
true

Grid

PropType
horizontal?boolean

Show horizontal grid lines.

Default
true
vertical?boolean

Show vertical grid lines.

Default
false
numTicksRows?number

Number of horizontal grid lines. Ignored when rowTickValues is set.

Default
5
numTicksColumns?number

Number of vertical grid lines.

Default
10
rowTickValues?number[]

Explicit y values for the horizontal grid lines. Overrides numTicksRows.

stroke?string

Color of the grid lines.

Default
"var(--chart-grid)"
loadingStroke?string

Grid color while the chart is loading. Falls back to stroke.

strokeOpacity?number

Opacity of the grid lines.

Default
1
strokeWidth?number

Width of the grid lines in px.

Default
1
strokeDasharray?string

Dash pattern of the grid lines.

Default
"4,4"
highlightRowValues?number[]

Y values of horizontal lines drawn with the highlight styling, for example a zero baseline.

highlightRowStroke?string

Color of the highlighted rows.

Default
"var(--chart-foreground-muted)"
highlightRowStrokeOpacity?number

Opacity of the highlighted rows.

Default
1
highlightRowStrokeWidth?number

Width of the highlighted rows in px.

Default
1
highlightRowStrokeDasharray?string

Dash pattern of the highlighted rows.

Default
"0"
fadeHorizontal?boolean

Fade the horizontal lines toward transparent at the left and right edges.

Default
true
fadeVertical?boolean

Fade the vertical lines toward transparent at the top and bottom edges.

Default
false
hideHorizontalEdgeLines?boolean

Drop the first and last horizontal line (kept when two or fewer remain).

Default
false
hideVerticalEdgeLines?boolean

Drop the first and last vertical line (kept when two or fewer remain).

Default
false
shimmer?boolean

While the chart is loading, sweep a bright band across the grid.

Default
false
shimmerStroke?string

Color of the shimmer band.

Default
"color-mix(in oklch, var(--bkm-foreground) 68%, transparent)"
shimmerSpeed?number

Speed multiplier of the shimmer sweep. 2 is twice as fast.

Default
1

EcdfXAxis

PropType
numTicks?number

Target number of tick labels on a value axis.

Default
5
formatLargeNumbers?boolean

Abbreviate values of 1000 and above as thousands, for example 2k or 1.5k. Ignored when formatValue is set.

Default
true
formatValue?(value: number) => string

Formats a value tick into its label, for example (value) => \${value} ms\``.

Type
(value: number) => string

EcdfYAxis

PropType
numTicks?number

Target number of tick labels on a value axis.

Default
5
formatLargeNumbers?boolean

Abbreviate values of 1000 and above as thousands, for example 2k or 1.5k. Ignored when formatValue is set.

Default
true
formatValue?(value: number) => string

Formats a value tick into its label, for example (value) => \${value} ms\``.

Type
(value: number) => string

EcdfTooltip

PropType
content?(context: DistributionTooltipContext<EcdfPoint>) => ReactNode

Replaces the default panel body (a title over one row per value) with your own content for the hovered item.

Type
(context: DistributionTooltipContext<EcdfPoint>) => ReactNode
formatValue?(value: number) => string

Formats the values the default body shows. Defaults to the chart's value axis formatValue, else en-US numbers.

Type
(value: number) => string

EcdfChartLoading

PropType
aspectRatio?string

Width to height ratio of the placeholder, for example "2 / 1".

Default
"2 / 1"
margin?Partial<ChartMargin>

Space around the plot in pixels, per side.

Type
Partial<ChartMargin>
label?string

Text shown centered over the skeleton, with a shimmer. Nothing is shown when it is unset or empty.

className?string

Class names added to the placeholder's container.

Default
""

Examples

3 examples on React, each live with its code and its own install command.

All 3 ecdf chart examples