Metrics
⋯
The Metrics family renders Line, Area, Bar, Pie, and Bar + Line Combo charts from the Figma sets,
and the plot-only .Line Chart Plot used in metric cards. The values, labels, and trends around a
plot are documented in Metric Card. Bands and markers draw on the cartesian
charts in data coordinates. Each chart uses Nesra tokens and accepts data and labels through a
bounded API.
import { AreaChart } from "@nesra/ui/area-chart";
export function DailyVisits() { return ( <AreaChart title="Daily visits" summary="Visits per day. Values are counts." data={[ { id: "mon", label: "Mon", values: { visits: 12 } }, { id: "tue", label: "Tue", values: { visits: 18 } }, ]} series={[{ key: "visits", label: "Visits", color: "orange" }]} /> );}All five charts are exported from @nesra/ui and their named subpaths. Consumers supply data,
series labels, chart token colors, and optional value formatters. The components own their
axes, tooltips, legends, and data tables. They do not forward Recharts configuration.
| Chart | Required data | Series definition |
|---|---|---|
| Line, Area, Bar | Ordered { id, label, values } categories |
Ordered { key, label, color } entries |
| Line Chart Plot | Ordered { id, label, values } categories |
Ordered { key, label, color } entries |
| Combo | Ordered { id, label, values } categories |
One barSeries and one lineSeries |
| Pie | Ordered { id, label, value, color? } slices |
None |
title names the figure. Write summary with the metric and units because the chart cannot infer
meaning from the numbers. Data fetching, error text, and interpretation belong to the application.
Colors and palettes
Section titled “Colors and palettes”A color is a ChartColor name that maps to a Nesra token, not an arbitrary CSS color.
| Palette | color values |
Token | Dark mode |
|---|---|---|---|
categorical |
blue, violet, red, orange, teal, yellow, then pink, indigo, purple, neutral. green is also accepted. |
--nesra-categorical-*-base |
Uses its Dark token value |
mono |
mono-9 to mono-1 |
--nesra-chart-mono-1 … 9 |
Scale reverses: mono-9 turns light |
blue |
blue-1 to blue-6 |
--nesra-chart-blue-1 … 6 |
Scale reverses: blue-1 turns dark |
The value order in each row is the order a chart assigns by position. The categorical order matches
Figma’s chart series: Blue, Violet, Red, Orange, Teal, Yellow. green is left out of that sequence
because it reads as a success signal. Mono starts at mono-9, the step with the most contrast
against the card. Blue starts at blue-1, like Figma’s filled pie.
A chart assigns palette colors only where it colors by position: single-series BarChart
categories and PieChart slices without their own color. Each takes a palette prop that
defaults to categorical. Line, Area, Combo, and Scatter series always use their own color, and
any ChartColor works there, for example mono-8 for a neutral comparison line.
Dark mode
Section titled “Dark mode”Charts read every color from tokens, so they follow the .dark class or [data-theme="dark"]
without props. In Dark:
- The card uses
surface-card-bg-neutral, and axis text and gridlines usetext-supportandstroke-border. - The
mono-*andblue-*scales reverse, so each step keeps its contrast against the card.mono-9andblue-6stay the strongest steps. - The tooltip is inverse: dark on a light page and light on a dark page. Its swatches keep their series color.
- The hover marker ring fills with
surface-card-bg-neutral, so it matches the card in both modes. - Bands and markers use categorical roles, which have their own Dark values. The marker ring uses
surface-card-bg-neutral.
Scatter Chart extends this foundation with two numeric axes and optional bubble sizes.
Examples
Section titled “Examples”Line Chart
Section titled “Line Chart”import { LineChart } from "@nesra/ui/line-chart";import { LineChart, type LineChartPoint, type LineChartSeries } from "@nesra/ui/line-chart";
// Synthetic values for this documentation example.const data: LineChartPoint[] = [ { id: "mon", label: "Mon", values: { visits: 124, signups: 42, trials: 18 } }, { id: "tue", label: "Tue", values: { visits: 148, signups: 48, trials: 22 } }, { id: "wed", label: "Wed", values: { visits: 139, signups: 53, trials: 25 } }, { id: "thu", label: "Thu", values: { visits: 173, signups: 57, trials: 31 } }, { id: "fri", label: "Fri", values: { visits: 190, signups: 64, trials: 34 } }, { id: "sat", label: "Sat", values: { visits: 168, signups: 61, trials: 28 } }, { id: "sun", label: "Sun", values: { visits: 203, signups: 70, trials: 39 } },];
const series: LineChartSeries[] = [ { key: "visits", label: "Visits", color: "orange" }, { key: "signups", label: "Sign-ups", color: "violet" }, { key: "trials", label: "Trials", color: "mono-8" },];
export function WeeklyActivityExample() { return ( <LineChart title="Weekly funnel activity" description="Synthetic example data for a seven-day period." summary="Visits rise during the week. The three lines show daily counts." data={data} series={series} formatValue={(value) => value.toLocaleString("en-US")} /> );}The example uses synthetic data. Orange and violet are categorical colors. mono-8 is the
monochrome comparison line from Figma. Each series also has a label and a distinct line pattern.
On hover or keyboard focus, Line, Area, and Combo charts show Figma’s .Chart Marker: a 10px ring in
the series color with a 2px stroke, filled with surface-card-bg-neutral. A dashed
stroke-border-strong guide marks the category. Line series show a line swatch in the tooltip.
Line Chart Plot
Section titled “Line Chart Plot”import { LineChartPlot } from "@nesra/ui/line-chart";import { LineChartPlot, type LineChartPoint, type LineChartSeries } from "@nesra/ui/line-chart";
// Synthetic values for this documentation example.const data: LineChartPoint[] = [ { id: "jul-01", label: "2026-07-01", values: { engagement: 5100 } }, { id: "jul-22", label: "2026-07-22", values: { engagement: 8600 } }, { id: "aug-08", label: "2026-08-08", values: { engagement: 7300 } }, { id: "aug-29", label: "2026-08-29", values: { engagement: 9800 } }, { id: "sep-15", label: "2026-09-15", values: { engagement: 16800 } }, { id: "oct-05", label: "2026-10-05", values: { engagement: 19900 } },];const series: LineChartSeries[] = [{ key: "engagement", label: "Engagement", color: "blue" }];
export function CompactPlotExample() { return ( <div className="w-full max-w-90 rounded-nesra-2xl border border-nesra-stroke-border bg-nesra-surface-card-bg-neutral p-nesra-padding-4xl"> <p className="type-nesra-body-large-semibold text-nesra-text-headline">Engagement</p> <LineChartPlot className="mt-nesra-spacing-xl" label="Engagement" summary="Engagement sessions from July to October. Synthetic example data." data={data} series={series} formatValue={(value) => `${(value / 1000).toFixed(2)}K`} /> </div> );}import { LineChartPlot, type LineChartPoint, type LineChartSeries } from "@nesra/ui/line-chart";
// Synthetic values for this documentation example.const values = [5100, 4900, 5300, 8600, 8200, 7300, 7600, 9800, 13200, 16800, 19900];const benchmark = [6200, 6100, 6400, 6900, 7100, 7400, 7600, 8100, 8600, 9200, 9800];const data: LineChartPoint[] = values.map((value, index) => ({ id: `week-${index + 1}`, label: `Week ${index + 1}`, values: { engagement: value, benchmark: benchmark[index]! },}));const series: LineChartSeries[] = [ { key: "engagement", label: "Engagement", color: "blue" }, { key: "benchmark", label: "Benchmark", color: "teal" },];
export function ExpandedPlotExample() { return ( <LineChartPlot size="expanded" label="Engagement compared with benchmark" summary="Weekly engagement sessions and the benchmark. Synthetic example data." data={data} series={series} formatValue={(value) => `${(value / 1000).toFixed(2)}K`} /> );}LineChartPlot renders Figma’s .Line Chart Plot: value and category axes, five gridlines, solid
lines, and the hover marker and tooltip. It has no title, legend, card surface, or padding. The
surrounding card supplies those. size="compact" is 200px tall for metric cards. size="expanded"
is 480px tall for the expanded view. showYAxis={false} hides the value labels.
Area Chart
Section titled “Area Chart”import { AreaChart } from "@nesra/ui/area-chart";import { AreaChart, type ChartPoint, type ChartSeries } from "@nesra/ui/area-chart";
// Synthetic values for this documentation example.const data: ChartPoint[] = [ { id: "mon", label: "Mon", values: { visits: 25, trials: 12 } }, { id: "tue", label: "Tue", values: { visits: 32, trials: 15 } }, { id: "wed", label: "Wed", values: { visits: 35, trials: 20 } }, { id: "thu", label: "Thu", values: { visits: 31, trials: 26 } }, { id: "fri", label: "Fri", values: { visits: 39, trials: 34 } }, { id: "sat", label: "Sat", values: { visits: 56, trials: 45 } }, { id: "sun", label: "Sun", values: { visits: 62, trials: 51 } },];const series: ChartSeries[] = [ { key: "visits", label: "Visits", color: "orange" }, { key: "trials", label: "Trials", color: "violet" },];
export function AreaExample() { return ( <AreaChart title="Weekly activity" description="Synthetic example data." summary="Daily visits and trials. Values are counts." data={data} series={series} xAxisLabel="Day" yAxisLabel="Count" /> );}Area series overlap independently. Values are not stacked. null leaves a gap. The default legend
position is bottom. legendPosition="top" moves it above the plot.
Bar Chart
Section titled “Bar Chart”import { BarChart } from "@nesra/ui/bar-chart";import { BarChart, type ChartPoint, type ChartSeries } from "@nesra/ui/bar-chart";
// Synthetic values for this documentation example.const data: ChartPoint[] = [ { id: "jan", label: "January", values: { basic: 24, pro: 48, team: 68 } }, { id: "feb", label: "February", values: { basic: 32, pro: 52, team: 72 } }, { id: "mar", label: "March", values: { basic: 39, pro: 58, team: 78 } }, { id: "apr", label: "April", values: { basic: 45, pro: 64, team: 84 } },];const series: ChartSeries[] = [ { key: "basic", label: "Basic", color: "blue" }, { key: "pro", label: "Pro", color: "violet" }, { key: "team", label: "Team", color: "red" },];
export function VerticalGroupedBarExample() { return ( <BarChart title="Monthly subscriptions" description="Synthetic example data." summary="Plan subscriptions by month. Values are counts." data={data} series={series} /> );}import { BarChart, type ChartPoint, type ChartSeries } from "@nesra/ui/bar-chart";
// Synthetic values for this documentation example.const data: ChartPoint[] = [ { id: "jan", label: "January", values: { basic: 24, pro: 48, team: 68 } }, { id: "feb", label: "February", values: { basic: 32, pro: 52, team: 72 } }, { id: "mar", label: "March", values: { basic: 39, pro: 58, team: 78 } }, { id: "apr", label: "April", values: { basic: 45, pro: 64, team: 84 } },];const series: ChartSeries[] = [ { key: "basic", label: "Basic", color: "blue" }, { key: "pro", label: "Pro", color: "violet" }, { key: "team", label: "Team", color: "red" },];
export function HorizontalGroupedBarExample() { return ( <BarChart title="Monthly subscriptions, horizontal" summary="Plan subscriptions by month. Values are counts." data={data} series={series} orientation="horizontal" /> );}import { BarChart, type ChartPoint, type ChartSeries } from "@nesra/ui/bar-chart";
// Synthetic values for this documentation example.const data: ChartPoint[] = [ { id: "jan", label: "January", values: { basic: 24 } }, { id: "feb", label: "February", values: { basic: 32 } }, { id: "mar", label: "March", values: { basic: 39 } }, { id: "apr", label: "April", values: { basic: 45 } },];const series: ChartSeries[] = [{ key: "basic", label: "Basic", color: "blue" }];
export function VerticalSingleBarExample() { return ( <BarChart title="Basic subscriptions" summary="Basic plan subscriptions by month. Values are counts." data={data} series={series} /> );}import { BarChart, type ChartPoint, type ChartSeries } from "@nesra/ui/bar-chart";
// Synthetic values for this documentation example.const data: ChartPoint[] = [ { id: "jan", label: "January", values: { basic: 24 } }, { id: "feb", label: "February", values: { basic: 32 } }, { id: "mar", label: "March", values: { basic: 39 } }, { id: "apr", label: "April", values: { basic: 45 } },];const series: ChartSeries[] = [{ key: "basic", label: "Basic", color: "blue" }];
export function HorizontalSingleBarExample() { return ( <BarChart title="Basic subscriptions, horizontal" summary="Basic plan subscriptions by month. Values are counts." data={data} series={series} orientation="horizontal" /> );}import { BarChart, type ChartPoint, type ChartSeries } from "@nesra/ui/bar-chart";
// Synthetic values for this documentation example.const data: ChartPoint[] = [ { id: "jan", label: "January", values: { basic: 24 } }, { id: "feb", label: "February", values: { basic: 32 } }, { id: "mar", label: "March", values: { basic: 39 } }, { id: "apr", label: "April", values: { basic: 45 } }, { id: "may", label: "May", values: { basic: 51 } }, { id: "jun", label: "June", values: { basic: 58 } },];const series: ChartSeries[] = [{ key: "basic", label: "Basic", color: "mono-8" }];
export function MonochromeSingleBarExample() { return ( <BarChart title="Basic subscriptions, monochrome" summary="Basic plan subscriptions by month. Values are counts." data={data} series={series} palette="mono" /> );}orientation="vertical" is the default. One series renders the single-bar design with a color per
category from palette. Multiple series render grouped bars with a color per series. Horizontal bars retain input
category order. The default legend position is top. legendPosition="bottom" moves it below.
Stacked bars
Section titled “Stacked bars”import { BarChart, type ChartPoint, type ChartSeries } from "@nesra/ui/bar-chart";
// Synthetic values for this documentation example.const data: ChartPoint[] = [ { id: "jan", label: "January", values: { basic: 24, pro: 48, team: 68 } }, { id: "feb", label: "February", values: { basic: 32, pro: 52, team: 72 } }, { id: "mar", label: "March", values: { basic: 39, pro: 58, team: 78 } }, { id: "apr", label: "April", values: { basic: 45, pro: 64, team: 84 } },];const series: ChartSeries[] = [ { key: "basic", label: "Basic", color: "mono-8" }, { key: "pro", label: "Pro", color: "mono-6" }, { key: "team", label: "Team", color: "mono-4" },];
export function StackedVerticalBarExample() { return ( <BarChart title="Monthly subscriptions by plan" description="Synthetic example data." summary="Total subscriptions by month, split by plan. Values are counts." data={data} series={series} stacked /> );}import { BarChart, type ChartPoint, type ChartSeries } from "@nesra/ui/bar-chart";
// Synthetic values for this documentation example.const data: ChartPoint[] = [ { id: "search", label: "Search", values: { new: 420, returning: 310 } }, { id: "social", label: "Social", values: { new: 360, returning: 140 } }, { id: "email", label: "Email", values: { new: 90, returning: 280 } },];const series: ChartSeries[] = [ { key: "new", label: "New visitors", color: "blue" }, { key: "returning", label: "Returning visitors", color: "violet" },];
export function StackedHorizontalBarExample() { return ( <BarChart title="Visitors by channel" description="Synthetic example data." summary="Visitors by acquisition channel, split into new and returning. Values are counts." data={data} series={series} orientation="horizontal" stacked /> );}stacked renders Figma’s Stacked Bar type. Series stack in order from the baseline, with a 2px gap
between segments. Only the outer end of each bar has a 4px radius. Stacked values must be finite
and nonnegative. Each series keeps its own color, and the legend lists the series.
Pie Chart
Section titled “Pie Chart”import { PieChart } from "@nesra/ui/pie-chart";import { PieChart, type PieChartPoint } from "@nesra/ui/pie-chart";
// Synthetic values for this documentation example.const data: PieChartPoint[] = [ { id: "basic", label: "Basic", value: 10 }, { id: "pro", label: "Pro", value: 20 }, { id: "team", label: "Team", value: 5 }, { id: "enterprise", label: "Enterprise", value: 10 }, { id: "education", label: "Education", value: 25 }, { id: "other", label: "Other", value: 30 },];
export function OutlinePieExample() { return ( <PieChart title="Subscriptions by plan" description="Synthetic example data." summary="Each slice shows its share of 100 subscriptions." data={data} centerLabel="Subscriptions" centerValue="100" /> );}import { PieChart, type PieChartPoint } from "@nesra/ui/pie-chart";
// Synthetic values for this documentation example.const data: PieChartPoint[] = [ { id: "basic", label: "Basic", value: 10 }, { id: "pro", label: "Pro", value: 20 }, { id: "team", label: "Team", value: 5 }, { id: "enterprise", label: "Enterprise", value: 10 }, { id: "education", label: "Education", value: 25 }, { id: "other", label: "Other", value: 30 },];
export function FilledPieExample() { return ( <PieChart title="Subscriptions by plan, filled" summary="Each slice shows its share of 100 subscriptions." data={data} variant="filled" palette="blue" /> );}variant="outline" renders a donut and may display centerLabel and centerValue. variant="filled"
renders a solid pie. Slices without a color take the next palette color. The examples follow
Figma: the donut uses categorical and the filled pie uses palette="blue". Data follows input order. Values must be finite and nonnegative. Zero values
remain in the table and contribute no slice. Shares are calculated from the total.
Bar + Line Combo Chart
Section titled “Bar + Line Combo Chart”import { ComboChart } from "@nesra/ui/combo-chart";import { ComboChart, type ChartPoint } from "@nesra/ui/combo-chart";
// Synthetic values for this documentation example.const data: ChartPoint[] = [ { id: "jan", label: "Jan", values: { signups: 120, rate: 12 } }, { id: "feb", label: "Feb", values: { signups: 98, rate: 16 } }, { id: "mar", label: "Mar", values: { signups: 150, rate: 18 } }, { id: "apr", label: "Apr", values: { signups: 105, rate: 22 } }, { id: "may", label: "May", values: { signups: 130, rate: 27 } }, { id: "jun", label: "Jun", values: { signups: 72, rate: 31 } },];
export function ComboExample() { return ( <ComboChart title="Sign-ups and conversion" description="Synthetic example data." summary="Monthly sign-ups are counts; conversion uses the right percentage scale." data={data} barSeries={{ key: "signups", label: "Sign-ups", color: "blue" }} lineSeries={{ key: "rate", label: "Conversion rate", color: "orange" }} formatLineValue={(value) => `${value}%`} /> );}barSeries uses the left numeric scale and lineSeries uses the right numeric scale. Format each
with formatBarValue and formatLineValue. Include the units in their labels and summary.
Overlays
Section titled “Overlays”import { ChartBand, ChartMarker } from "@nesra/ui/chart-overlay";import { ChartBand, ChartMarker } from "@nesra/ui/chart-overlay";import { LineChart, type LineChartPoint, type LineChartSeries } from "@nesra/ui/line-chart";
// Synthetic values for this documentation example.const data: LineChartPoint[] = [ { id: "sep-29", label: "Sep 29", values: { visits: 5200 } }, { id: "sep-30", label: "Sep 30", values: { visits: 5600 } }, { id: "oct-1", label: "Oct 1", values: { visits: 6100 } }, { id: "oct-2", label: "Oct 2", values: { visits: 5900 } }, { id: "oct-3", label: "Oct 3", values: { visits: 6400 } }, { id: "oct-4", label: "Oct 4", values: { visits: 7000 } }, { id: "oct-5", label: "Oct 5", values: { visits: 9800 } },];const series: LineChartSeries[] = [{ key: "visits", label: "Visits", color: "blue" }];
export function ExpectedRangeExample() { return ( <LineChart title="Daily visits" description="Synthetic example data." summary="Visits per day. Oct 5 is above the expected range of 5,000 to 7,500." data={data} series={series} formatValue={(value) => value.toLocaleString("en-US")} > <ChartBand axis="value" from={5000} to={7500} label="Expected range" color="teal" /> <ChartMarker category="oct-2" label="Budget raised on Oct 2" /> <ChartMarker category="oct-5" value={9800} label="Anomaly on Oct 5" color="teal" /> </LineChart> );}import { BarChart, type ChartPoint, type ChartSeries } from "@nesra/ui/bar-chart";import { ChartBand } from "@nesra/ui/chart-overlay";
// Synthetic values for this documentation example.const data: ChartPoint[] = [ { id: "w1", label: "Week 1", values: { orders: 320 } }, { id: "w2", label: "Week 2", values: { orders: 340 } }, { id: "w3", label: "Week 3", values: { orders: 510 } }, { id: "w4", label: "Week 4", values: { orders: 560 } }, { id: "w5", label: "Week 5", values: { orders: 360 } },];const series: ChartSeries[] = [{ key: "orders", label: "Orders", color: "mono-8" }];
export function CategoryBandExample() { return ( <BarChart title="Weekly orders" description="Synthetic example data." summary="Orders per week. Weeks 3 and 4 ran the spring campaign." data={data} series={series} palette="mono" > <ChartBand axis="category" from="w3" to="w4" label="Spring campaign" color="violet" /> </BarChart> );}Place ChartBand and ChartMarker as children of LineChart, AreaChart, BarChart, ComboChart,
or LineChartPlot. They take data coordinates: a point id for a category and a number for a value.
Components that render them, such as a wrapper with preset props, also work.
ChartBand axis="value"fills the range between two values across the plot.axis="category"fills from the first category to the last, along the plot. The fill iscategorical-{color}-baseat 15% opacity, with 1px dashed edges incategorical-{color}-border.ChartMarkerwith avaluedraws a dot on that point and a dashed guide down to the category axis. Without avalue, it draws only a guide across the plot.activeenlarges the dot and shows a halo.- Value coordinates use the first value scale: the bar scale in
ComboChartand the horizontal scale in a horizontalBarChart. The scale does not grow to include an overlay. A band outside it is clipped to the plot.
Interactive markers
Section titled “Interactive markers”import { useRef, useState } from "react";import { ChartMarker } from "@nesra/ui/chart-overlay";import { LineChart, type LineChartPoint, type LineChartSeries } from "@nesra/ui/line-chart";import { Popover } from "@nesra/ui/popover";
// Synthetic values for this documentation example.const data: LineChartPoint[] = [ { id: "oct-1", label: "Oct 1", values: { visits: 6100 } }, { id: "oct-2", label: "Oct 2", values: { visits: 5900 } }, { id: "oct-3", label: "Oct 3", values: { visits: 6400 } }, { id: "oct-4", label: "Oct 4", values: { visits: 7000 } }, { id: "oct-5", label: "Oct 5", values: { visits: 9800 } },];const series: LineChartSeries[] = [{ key: "visits", label: "Visits", color: "blue" }];
export function InteractiveMarkerExample() { const marker = useRef<SVGGElement>(null); const [open, setOpen] = useState(false); return ( <> <LineChart title="Daily visits" description="Synthetic example data." summary="Visits per day. Select the Oct 5 marker for details." data={data} series={series} formatValue={(value) => value.toLocaleString("en-US")} > <ChartMarker ref={marker} category="oct-5" value={9800} label="Anomaly on Oct 5" color="teal" active={open} aria-expanded={open} aria-haspopup="dialog" onClick={() => setOpen(true)} /> </LineChart> <Popover open={open} onOpenChange={setOpen}> <Popover.Content anchor={marker} side="right" finalFocus={() => { marker.current?.focus(); return false; }} > <Popover.Title>Unusual spike on Oct 5</Popover.Title> <Popover.Description> 9,800 visits, above the expected 5,000 to 7,500. </Popover.Description> </Popover.Content> </Popover> </> );}A marker with onClick renders as a focusable button. Enter and Space activate it. Pass ref to
anchor a popover to the marker, and set aria-expanded and active while it is open. The marker is
not the popover’s trigger, so return focus to it on close with a finalFocus function, as in the
example. The application owns the popover content and its open state.
Accessibility
Section titled “Accessibility”- The visible
summarydescribes meaning and units. The component does not infer trends from values. - Tab to the plot, then use Left and Right Arrow to discover a category’s values in the floating tooltip. Escape dismisses the tooltip. Pointer hover exposes the same values.
- Every chart includes a visually hidden native table of all categories and series, so screen readers can read each value. Missing values read “No value.” Figma does not define a visible data disclosure, so the table has no visible control.
- Keep series labels meaningful. Colors supplement labels. Line Chart also uses distinct line patterns.
- The lightest
mono-*andblue-*steps sit close to the card color. Use them next to stronger steps, as in a pie, rather than as the only mark in a plot. - The plot and the Scatter plot show the
shadow-nesra-focus-ringring on keyboard focus. - Pie charts list every slice and its share beside the plot. Their native table includes exact values and shares. Consumers should keep labels concise and distinct.
LineChartPlothas no visible title.labelnames the figure, andsummarydescribes it for screen readers. Like the full charts, it carries every value in a visually hidden native table.- Overlays add a text line each after the hidden table, such as “Expected range: 5,000 to 7,500.” A marker’s
labelis its accessible name. Write it with the date and meaning, such as “Anomaly on Oct 5.” - A marker without
onClickis a labelled image and not a Tab stop. WithonClick, it is a button after the plot in Tab order and shows theeffects-focus-ringring on keyboard focus. - Plot and tooltip animations follow the user’s reduced-motion preference. When reduced motion is requested, values and hover states appear without animation.
- Verify the summary and values against the application’s actual data. The consuming application owns data fetching, error copy, and any important interpretation of the trend.
API reference
Section titled “API reference”Line, Area, Bar, and Combo use ordered { id, label, values } rows. Point IDs and series keys must
be nonempty and unique. Every point needs a value for every series key. Each value must be finite
or null. null means missing, never zero. Pie slice IDs must also be nonempty and unique.
All five charts accept figure attributes except the native title and children props, which
their own layout controls.
Shared chart props
Section titled “Shared chart props”These props apply to Line, Area, Bar, Combo, and Pie. Each chart renders a visually hidden native data table when values are available.
| Prop | Type | Default | Effect |
|---|---|---|---|
title |
string |
required | Visible heading and accessible figure name. |
summary |
string |
required | Visible meaning and units, written by the consumer. |
description |
string |
— | Supporting text beneath the title. |
loading |
boolean |
false |
Shows loading status and sets aria-busy. |
error |
string | null |
— | Shows consumer-supplied error text instead of a plot. |
className |
string |
— | Adds or overrides outer figure classes. |
Empty data renders an empty status. A consumer supplies status text through error when data
fetching fails.
Line, Area, Bar, and Combo also accept the axis legend props from Figma’s .Chart Legend:
| Prop | Type | Default | Effect |
|---|---|---|---|
xAxisLabel |
string |
— | Shows “X-axis:” in text-support, then this name in text-body. |
yAxisLabel |
string |
— | Shows “Y-axis:” in text-support, then this name in text-body. |
The axis legend sits above the series legend, in Body/XSmall Regular, and renders only for the
labels given. The “X-axis:” and “Y-axis:” prefixes are translatable through NesraI18nProvider.
LineChart
Section titled “LineChart”| Prop | Type | Default | Effect |
|---|---|---|---|
data |
LineChartPoint[] |
required | Ordered { id, label, values } categories. IDs must be unique. Each series key needs a finite number or null. |
series |
LineChartSeries[] |
required | At least one ordered { key, label, color } definition. Keys must be unique. |
formatValue |
(value: number) => string |
String |
Formats ticks, tooltip values, and table cells. |
formatCategory |
(label: string) => string |
identity | Formats category ticks, tooltip labels, and table row headings. |
children |
ReactNode |
— | ChartBand and ChartMarker overlays. Their text is listed after the hidden data table. |
null creates a gap. It never means zero. Empty data and data with only missing values show an
empty status. The categorical horizontal scale follows input order. The vertical numeric scale
includes zero. The plot fills its container. Other
native figure attributes are forwarded.
AreaChart
Section titled “AreaChart”| Prop | Type | Default | Effect |
|---|---|---|---|
data |
ChartPoint[] |
required | Ordered categories with one value per series. |
series |
ChartSeries[] |
required | Ordered area labels and chart colors. |
formatValue |
(value: number) => string |
String |
Formats ticks, tooltip values, and table cells. |
formatCategory |
(label: string) => string |
identity | Formats category labels and table row headings. |
legendPosition |
"top" | "bottom" |
"bottom" |
Places the legend above or below the plot. |
children |
ReactNode |
— | ChartBand and ChartMarker overlays. |
Areas overlap independently and are not stacked. null leaves a gap. AreaChart inherits the
shared chart props and forwards native figure attributes other than title and children.
BarChart
Section titled “BarChart”| Prop | Type | Default | Effect |
|---|---|---|---|
data |
ChartPoint[] |
required | Ordered categories with one value per series. |
series |
ChartSeries[] |
required | One series colors categories. Multiple series group bars. |
orientation |
"vertical" | "horizontal" |
"vertical" |
Chooses bar and category-axis direction. |
palette |
"categorical" | "mono" | "blue" |
"categorical" |
Colors each category when there is one series. |
formatValue |
(value: number) => string |
String |
Formats ticks, tooltip values, and table cells. |
formatCategory |
(label: string) => string |
identity | Formats category labels and table row headings. |
legendPosition |
"top" | "bottom" |
"top" |
Places the legend above or below the plot. |
stacked |
boolean |
false |
Stacks series into one bar per category, from the baseline. |
children |
ReactNode |
— | ChartBand and ChartMarker overlays. |
stacked throws for a negative value. Horizontal bars keep input category order. BarChart inherits the shared chart props and forwards
native figure attributes other than title and children.
ComboChart
Section titled “ComboChart”| Prop | Type | Default | Effect |
|---|---|---|---|
data |
ChartPoint[] |
required | Ordered categories with bar and line values. |
barSeries |
ChartSeries |
required | Bar label, color, and left numeric scale. |
lineSeries |
ChartSeries |
required | Line label, color, and right numeric scale. |
formatBarValue |
(value: number) => string |
String |
Formats left ticks, bar tooltip and table values. |
formatLineValue |
(value: number) => string |
String |
Formats right ticks, line tooltip and table values. |
formatCategory |
(label: string) => string |
identity | Formats category labels and table row headings. |
legendPosition |
"top" | "bottom" |
"bottom" |
Places the legend above or below the plot. |
children |
ReactNode |
— | ChartBand and ChartMarker overlays. |
The bar and line scales include zero independently. Hovering a category draws Figma’s Detail Line:
a dashed stroke-border-strong line through the middle of the category, like Line and Area. As in
Figma, it sits above the bars and the line. The line’s hover ring stays above it. Bar
charts shade the hovered category with foundation-bg-gray instead. ComboChart inherits the
shared chart props and forwards native figure attributes other than title and children.
PieChart
Section titled “PieChart”| Prop | Type | Default | Effect |
|---|---|---|---|
data |
PieChartPoint[] |
required | Ordered { id, label, value, color? } slices. |
variant |
"outline" | "filled" |
"outline" |
Renders a donut or solid pie. |
palette |
"categorical" | "mono" | "blue" |
"categorical" |
Colors slices that have no color, in data order. |
centerLabel |
string |
— | Places a label inside the outline donut. |
centerValue |
string |
— | Places a value inside the outline donut. |
formatValue |
(value: number) => string |
String |
Formats tooltip and table values. |
Pie values must be finite and nonnegative. Zero values remain in the table but contribute no slice.
A zero total renders an empty status. The table includes exact values and computed shares.
PieChart inherits the shared chart props and forwards native figure attributes other than
title and children.
LineChartPlot
Section titled “LineChartPlot”| Prop | Type | Default | Effect |
|---|---|---|---|
label |
string |
required | Accessible figure name. Not displayed. |
summary |
string |
required | Meaning and units, for screen readers only. |
data |
LineChartPoint[] |
required | Ordered { id, label, values } categories, as in LineChart. |
series |
LineChartSeries[] |
required | Ordered { key, label, color } lines. |
size |
"compact" | "expanded" |
"compact" |
Total height: 200px or 480px, including the category axis. |
showYAxis |
boolean |
true |
Shows the value axis labels. |
formatValue |
(value: number) => string |
String |
Formats value ticks, tooltip values, and hidden table cells. |
formatCategory |
(label: string) => string |
identity | Formats category ticks, tooltip labels, and hidden table headings. |
children |
ReactNode |
— | ChartBand and ChartMarker overlays. |
The plot fills its container width. Data with only missing values shows an empty status at the
same height. LineChartPlot forwards native figure attributes other than title and children.
It has no loading or error state. The surrounding card owns those.
ChartBand
Section titled “ChartBand”| Prop | Type | Default | Effect |
|---|---|---|---|
axis |
"value" | "category" |
required | Chooses value or category coordinates for from and to. |
from |
number for value, string for category |
required | Range start: a value, or a point id. |
to |
number for value, string for category |
required | Range end: a value, or a point id. Either order works for values. |
label |
string |
required | Meaning of the range. Listed with the data as “label: from to to.” |
color |
CategoricalColor |
"neutral" |
Fill categorical-{color}-base at 15% and edges categorical-{color}-border. |
Values must be finite. A category id that is not in data throws. The band is hidden from
assistive technology inside the plot because its text is listed with the data.
ChartMarker
Section titled “ChartMarker”| Prop | Type | Default | Effect |
|---|---|---|---|
category |
string |
required | Point id of the marked category. |
value |
number |
— | Draws the dot at this value. Omit it for a guide across the plot. |
label |
string |
required | Accessible name and annotation text. |
color |
CategoricalColor |
"neutral" |
Dot, guide, and halo colors. See below. |
active |
boolean |
false |
Enlarges the dot from 14px to 18px and shows a 24px halo. |
onClick |
SVG click handler | — | Makes the marker a focusable button that Enter and Space activate. |
ref |
Ref<SVGGElement> |
— | Receives the marker group, for example as a popover anchor. |
A categorical color uses categorical-{color}-strong for the dot, -border for the guide, and
-subtle-hover for the halo. neutral uses icon-muted, stroke-border, and
foundation-bg-disabled, which are Figma’s neutral (Event) marker roles. The dot has a 2px
surface-card-bg-neutral ring. ChartMarker forwards other SVG group attributes and event
handlers, such as aria-expanded.
Both overlays throw outside a cartesian chart. PieChart and ScatterChart do not accept them.
ChartColor, ChartPalette, ChartMonoColor, ChartBlueColor, and CategoricalColor are
exported as types from @nesra/ui. ChartBandProps, ChartValueBandProps,
ChartCategoryBandProps, ChartMarkerProps, and LineChartPlotProps are also exported.
See colors, typography, layout, and shape and elevation for the token contract.
Upcoming chart types
Section titled “Upcoming chart types”Not available yet
Other chart types have no supported Nesra UI import yet.