Setup

The Once UI data-viz module is a collection of opinionated chart solutions built on top of Recharts and Date-fns. It was designed to help you create beautiful and interactive charts with minimal code.

GDP Growth vs. CO₂ Emissions

Config

The default settings for the data viz module are stored in the src/resources/data.config.js file. You can use it to define the default height, highlight color, data mode and variant.

Config

variant: "gradient", // flat | gradient | outline
mode: "categorical", // categorical | divergent | sequential
height: 24, // default chart height
axisLine: {
  stroke: "var(--neutral-alpha-weak)",
},
tick: {
  fill: "var(--neutral-on-background-weak)",
  fontSize: 11,
},
tickLine: false,

Props

All charts share the same props for common settings, so it's easy to swap between different chart types with minimal code changes. Each chart may have additional, chart-specific props. Every chart takes these. The sections below walk through the ones worth explaining; this is the whole list.

Prop	Type	Default
title Heading above the chart.	React.ReactNode	—
description Supporting line under the title.	React.ReactNode	—
seriesrequired Which keys in `data` to plot, and optionally what colour each is.	SeriesConfigSeriesConfig[]	—
datarequired The rows. Each needs the keys named in `series`, plus whatever the x axis reads.	DataPoint[]	—
legend Legend position and visibility.	LegendConfig	—
date Format and range for a time axis.	DateConfig	—
emptyState What to show when `data` is empty.	React.ReactNode	—
errorState What to show when `error` is set.	React.ReactNode	—
error Render the error state instead of the chart.	boolean	—
tooltip Show a tooltip on hover.	boolean	—
grid Which grid lines to draw. Chart types differ in what they default to.	xybothnone	—
axis Which axes to label.	xybothnone	—
variant Fill treatment for the plotted area.	flatoutlinegradient	—
loading Render the loading state instead of the chart.	boolean	—

Data

Use the series and data props to define the chart data to render, and assign colors to override defaults. The series prop is an array of objects, where each object has a key property that defines the name of the series, and an optional color property that defines the color of the series. Match the key property with the property name in the data prop.

Data

Daily Time Spent on Activities

<BarChart
  title="Daily Time Spent on Activities"
  axis="none"
  barWidth="xl"
  legend={{
    position: "bottom-center",
  }}
  series={[
    { key: "Reading", color: "aqua" },
    { key: "Sports", color: "yellow" },
    { key: "Doomscrolling", color: "orange" }
  ]}
  data={[
    { label: "Minutes per day", "Reading": 16, "Sports": 36, "Doomscrolling": 128 },
  ]}
/>

Prop	Type	Default
series	{[{key: string, color?: string}]}	—
data	{[{date: string, [key: string]: number}]}	—

When working with time series data, use the date prop to define the date format. Alternatively, you can translate the date values to Date objects to render the dates based on the default format.

Details

Cost of College vs. Income

<LineChart
  title="Cost of College vs. Income"
  axis="x"
  date={{
    format: "yyyy"
  }}
  series={[
    { key: "Median Household Income", color: "cyan" },
    { key: "College Tuition", color: "magenta" }
  ]}
  data={[
    { date: new Date("1980-01-01"), "Median Household Income": 22000, "College Tuition": 3000 },
    { date: new Date("1990-01-01"), "Median Household Income": 30000, "College Tuition": 6000 },
    { date: new Date("2000-01-01"), "Median Household Income": 42000, "College Tuition": 10000 },
    { date: new Date("2010-01-01"), "Median Household Income": 49000, "College Tuition": 18000 },
    { date: new Date("2020-01-01"), "Median Household Income": 53000, "College Tuition": 25000 },
  ]}
/>

Context

Render textual context above the chart with the title and description props.

Wealth distributionGlobal share of wealth held by Top 1% vs Bottom 99%

<BarChart
  title="Wealth distribution"
  description="Global share of wealth held by Top 1% vs Bottom 99%"
  axis="none"
  legend={{
    position: "bottom-center"
  }}
  series={[
    { key: "Top 1%" },
    { key: "Bottom 99%" }
  ]}
  data={[
    { label: "2025 (est.)", "Top 1%": 52.5, "Bottom 99%": 47.5 }
  ]}
/>

Prop	Type	Default
title	ReactNode	—
description	ReactNode	—

Axis

Use the axis prop to control the visibility of the x and y axis.

CEO vs Employee Paycheck

<LineChart
  title="CEO vs Employee Paycheck"
  axis="both" // x | y | both | none
  date={{
    format: "yyyy"
  }}
  series={[
    { key: "Employee Paycheck", color: "green" },
    { key: "CEO Paycheck", color: "red" }
  ]}
  data={[
    { date: new Date("1980-01-01"), "CEO Paycheck": 500000, "Employee Paycheck": 25000 },
    { date: new Date("1990-01-01"), "CEO Paycheck": 800000, "Employee Paycheck": 30000 },
    { date: new Date("2000-01-01"), "CEO Paycheck": 1200000, "Employee Paycheck": 33000 },
    { date: new Date("2010-01-01"), "CEO Paycheck": 1600000, "Employee Paycheck": 35000 },
    { date: new Date("2020-01-01"), "CEO Paycheck": 3000000, "Employee Paycheck": 40000 },
  ]}
/>

Prop	Type	Default
axis	xybothnone	both

Legend

Use the legend prop to control the visibility, position, and direction of the legend.

Carbon Emission by Country

<PieChart
  title="Carbon Emission by Country"
  legend={{
    display: true,
    position: "bottom-center", // top-left | top-center | top-right | bottom-left | bottom-center | bottom-right
  }}
  ring={{ inner: 60, outer: 70 }}
  series={{
    key: "value",
  }}
  data={[
    { name: "EU", value: 7 },
    { name: "China", value: 28 },
    { name: "United States", value: 14 },
    { name: "Rest of the World", value: 51 }
  ]}
/>

Prop	Type	Default
legend	{{display: boolean, position: Position}}	—

Date

Use the date prop to define the date format and datepicker visibility and options.

Details

CEO vs Employee Paycheck

<LineBarChart
  marginTop="16"
  title="CEO vs Employee Paycheck"
  axis="both"
  date={{
    format: "yyyy",
    start: new Date("2000-01-01"),
    end: new Date("2020-01-01"),
    selector: true,
    presets: {
      display: true,
      granularity: "week"
    },
    dual: true
  }}
  series={[
    { key: "Screen Time (hrs)", color: "moss" },
    { key: "Physical Activity (hrs)", color: "yellow" }
  ]}
  data={[
    { date: new Date("2000-01-01"), "Screen Time (hrs)": 2.5, "Physical Activity (hrs)": 1.8 },
    { date: new Date("2005-01-01"), "Screen Time (hrs)": 3.0, "Physical Activity (hrs)": 1.6 },
    { date: new Date("2010-01-01"), "Screen Time (hrs)": 4.0, "Physical Activity (hrs)": 1.3 },
    { date: new Date("2015-01-01"), "Screen Time (hrs)": 5.5, "Physical Activity (hrs)": 1.0 },
    { date: new Date("2020-01-01"), "Screen Time (hrs)": 7.0, "Physical Activity (hrs)": 0.8 },
  ]}
/>

Prop	Type	Default
date	{{format: string, start: Date, end: Date, selector: boolean, presets: { display: boolean, granularity: string }, dual: boolean}}	—

Variants

Set the variant prop to gradient, flat, or outline to change the chart's appearance.

Details

<LineChart
  variant="outline" // gradient | flat | outline
  axis="x"
  legend={{
    display: false,
  }}
  date={{
    format: "yyyy"
  }}
  series={[
    { key: "Area (km²)", color: "contrast" },
    { key: "Temp Anomaly (°C)", color: "red" }
  ]}
  data={[
    { date: "1950-01-01", "Area (km²)": 4.2, "Temp Anomaly (°C)": 0.6 },
    { date: "1975-01-01", "Area (km²)": 3.4, "Temp Anomaly (°C)": 0.9 },
    { date: "2000-01-01", "Area (km²)": 2.3, "Temp Anomaly (°C)": 1.1 },
    { date: "2025-01-01", "Area (km²)": 1.2, "Temp Anomaly (°C)": 1.4 }
  ]}
/>

Prop	Type	Default
variant	gradientflatoutline	gradient

Color modes

Use the data-viz-style prop to change the chart's color mode to categorical, divergent, or sequential.

Tesla employee vs Elon Musk vs HungaryMonthly compensation / state budget

Colors are assigned automatically. You can override them in the series prop.

Tesla employee vs Elon Musk vs HungaryMonthly compensation / state budget

When using data-viz-style="divergent" or data-viz-style="sequential", we recommend using the default colors, since they are distributed evenly.

Tesla employee vs Elon Musk vs HungaryMonthly compensation / state budget

<LineChart
  data-viz-style="divergent" // categorical | divergent | sequential
  title="Tesla employee vs Elon Musk vs Hungary"
  description="Monthly compensation / state budget"
  axis="x"
  curve="step"
  date={{
    format: "yyyy",
  }}
  series={[
    { key: "Tesla Employee" },
    { key: "Elon Musk" },
    { key: "Hungary" }
  ]}
  data={[
    { date: "2000-01-01", "Elon Musk": 5000, "Tesla Employee": 3000, "Hungary": 2500000000 },
    { date: "2005-01-01", "Elon Musk": 5000, "Tesla Employee": 4200, "Hungary": 4000000000 },
    { date: "2010-01-01", "Elon Musk": 0, "Tesla Employee": 5500, "Hungary": 5000000000 },
    { date: "2015-01-01", "Elon Musk": 10000, "Tesla Employee": 6300, "Hungary": 6000000000 },
    { date: "2018-01-01", "Elon Musk": 100000000, "Tesla Employee": 7000, "Hungary": 6800000000 },
    { date: "2020-01-01", "Elon Musk": 2800000000, "Tesla Employee": 7600, "Hungary": 7500000000 },
    { date: "2023-01-01", "Elon Musk": 4500000000, "Tesla Employee": 8300, "Hungary": 7900000000 },
    { date: "2025-01-01", "Elon Musk": 5600000000, "Tesla Employee": 8800, "Hungary": 8200000000 }
  ]}
/>

Prop	Type	Default
data-viz-style Overrides the DataThemeProvider mode for this chart only. Falls back to the provider value.	categoricaldivergentsequential	—

Style overrides

You can override the default container styles with Flex props.

The TikTok TakeoverAvg. daily time spent per user on TikTok (minutes)

<BarChart
  marginTop="16"
  marginBottom="24"
  border="brand-alpha-medium"
  background="brand-weak"
  title="The TikTok Takeover"
  description="Avg. daily time spent per user on TikTok (minutes)"
  barWidth="xl"
  legend={{
    display: false
  }}
  series={{
    key: "Minutes",
    color: "contrast"
  }}
  data={[
    { date: "2020-01-01", Minutes: 20, label: "2020" },
    { date: "2021-01-01", Minutes: 40, label: "2021" },
    { date: "2022-01-01", Minutes: 65, label: "2022" },
    { date: "2023-01-01", Minutes: 85, label: "2023" },
    { date: "2024-01-01", Minutes: 95, label: "2024" },
    { date: "2025-01-01", Minutes: 180, label: "2025 (proj.)" }
  ]}
/>

Prop	Type	Default
…and every FlexProps prop	inherited	—

State

Charts fetch nothing themselves, so the four states of a request are props you set from wherever the data comes from. Handle them and a chart degrades into a readable panel rather than an empty frame.

Prop	Type	Default
loading Show the loading state instead of the chart.	boolean	false
error Show the error state instead of the chart.	boolean	false
emptyState Replaces the default message when data is empty.	ReactNode	—
errorState Replaces the default message when error is set.	ReactNode	—

Request states

const { data, isLoading, error } = useMetrics();

<LineChart
title="Revenue"
loading={isLoading}
error={Boolean(error)}
errorState={<Text onBackground="danger-weak">{error?.message}</Text>}
emptyState={<Text onBackground="neutral-weak">No revenue in this range yet.</Text>}
series={{ key: "Revenue" }}
data={data ?? []}
/>

An empty data array is not an error — it means the query ran and matched nothing, which is why emptyState is separate from errorState. Passing loading rather than withholding the chart keeps the panel's height stable, so the page does not jump when the data lands.

Prop	Type	Default
grid Which grid lines to draw. Bar charts default to y, line charts to both.	xybothnone	varies
tooltip Show the hover tooltip.	boolean	true

grid and axis are separate on purpose: a bar chart usually wants horizontal guides to compare heights against (grid="y") while still labelling both axes, and a sparkline-style chart wants axis="none" with the grid left on.

Config

Props

Data

Context

Axis

Legend

Date

Variants

Color modes

Style overrides

State

Grid and tooltip