Scatter chart

Campaign results
Point	Group	Spend	Sign-ups	Reach
Brand search	Search	$4,200	610	18,000
Competitor terms	Search	$9,800	720	22,000
Product search	Search	$14,500	1,380	31,000
Shopping ads	Search	$21,000	1,690	42,000
Generic terms	Search	$27,500	1,540	50,000
Launch video	Social	$6,400	290	64,000
Creator series	Social	$12,800	820	71,000
Carousel ads	Social	$18,200	760	48,000
Story ads	Social	$24,600	1,120	83,000
Lookalike audiences	Social	$33,800	1,470	96,000
Welcome series	Email	$1,800	540	9,000
Newsletter feature	Email	$3,100	460	14,000
Win-back	Email	$5,200	830	12,000
Partner list	Email	$8,600	690	21,000

Usage

Import the component and the stylesheet once. See Getting started to install the package.

import { ScatterChartCard } from '@lilt-ui/charts';
import '@lilt-ui/charts/styles.css';

<ScatterChartCard
  title="Campaign results"
  data={campaignResults}
  x="spend"
  y="signups"
  label="campaign"
/>

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

Each row is one point: x places it across, y places it up and feeds the headline, and TypeScript rejects anything but numeric fields for both. label names a point when it is read; size scales bubbles by area, so a point twice the value covers twice the ink; group colors points and adds a legend. A row missing x or y can’t be placed, so it is left off the plot, counted in the footer, and still listed for screen readers. Axes start at zero when the data starts near it, and at a round number otherwise.

// One row per point.
const campaignResults = [
  { campaign: 'Brand search', channel: 'Search', spend: 4200, signups: 610, reach: 18000 },
  { campaign: 'Story ads', channel: 'Social', spend: 24600, signups: null, reach: 83000 },
  // …
];

<ScatterChartCard
  title="Campaign results"
  data={campaignResults}
  x="spend"        // a numeric field: across
  y="signups"      // a numeric field: up, and the headline
  label="campaign" // a text field that names each point
  size="reach"     // optional: a numeric field for bubble area
  group="channel"  // optional: a text field for color and legend
/>

For a working period select, pass ranges. Each range brings its own data and delta.

<ScatterChartCard
  title="Campaign results"
  x="spend"
  y="signups"
  label="campaign"
  ranges={[
    { id: 'quarter', label: 'This quarter', data: thisQuarter, delta: 0.198 },
    { id: 'last-quarter', label: 'Last quarter', data: lastQuarter, delta: 0.074 },
  ]}
/>

Strip and beeswarm

StripChartCard shows individual measurements within categories, with mean as the default headline. Strip uses stable vertical jitter; beeswarm prevents collisions and expands the plot when needed. Both preserve each numeric position. Missing values are counted and remain in the accessible table. Unique labels preserve pin identity across updates.

import { StripChartCard } from '@lilt-ui/charts';

<StripChartCard data={deliveryTimes} category="carrier" value="hours" label="parcel" display="beeswarm" depth />

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'`	Resting headline summary; Strip defaults to mean, the others to sum.
`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.
`category`	`text key of Row`	Category lane for each point.
`value`	`numeric key of Row`	Measured horizontal position.
`label`	`text key of Row`	Unique accessible point name; falls back to row index.
`display`	`'strip' \| 'beeswarm'`	Stable jitter (default) or collision-free placement.
`radius`	`number`	Point radius in pixels, 2–12; default 4.
`onKeyDown`	`KeyboardEventHandler<HTMLElement>`	Keyboard handler on the card frame. Chart inspection also has its own keyboard handling.

Props

Every prop ScatterChartCard 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.
`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.
`trails`	`boolean`	Join successive observations within each group. Gaps break trails; duplicate or missing time keys suppress that group’s trail.
`trailOrder`	`numeric key of Row`	Explicit numeric time order. Otherwise follows input row order.
`data`	`Row[]`	One row per point. Omit when using ranges.
`x`	`numeric key of Row`	Places each point across.
`y`	`numeric key of Row`	Places each point up, and drives the headline.
`label`	`text key of Row`	Names a point when it is read. Unique labels also keep points steady across periods.
`size`	`numeric key of Row`	Sizes points by area, turning dots into bubbles.
`sizeLabel`	`string`	Names the size measure, e.g. “Reach”.
`group`	`text key of Row`	Colors points by group and adds a legend with each group’s value.
`xLabel`	`string`	Title for the horizontal axis.
`yLabel`	`string`	Title for the vertical axis.
`xFormat`	`Intl.NumberFormatOptions`	Formats x values and ticks, e.g. currency or seconds.
`trend`	`boolean`	A least-squares line through the points, with its r² in the footer.
`aggregate`	`'sum' \| 'mean' \| 'max'`	How the resting headline sums up every plotted y. Sum by default.
`height`	`number`	Plot height in pixels, including the axes. Defaults to 260.
`headline`	`number`	Resting headline. Defaults to the aggregate of every plotted y.
`delta`	`number`	Fractional change for the chip.
`deltaTone`	`'default' \| 'inverse' \| 'neutral'`	Use inverse when a decrease is good.
`range`	`string`	Static period label in the header.
`ranges`	`{ id, label, data, delta?, headline? }[]`	Turns the period label into a select. Each range swaps the points.
`color`	`string`	Any CSS color for points without a group.
`depth`	`boolean`	Draws each point as a lit sphere with a soft contact shadow. Centers and sizes stay exact.
`legend`	`false \| 'tiles' \| 'inline' \| 'list' \| 'pills' \| 'bars'`	False removes the legend without changing the data. How the group legend lays out: value tiles (default), a compact inline key, list rows, tinted pills, or bars against the largest.
`legendSwatch`	`'square' \| 'dot' \| 'line'`	The mark beside each legend label. Defaults to a rounded square.
`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.
`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.
`formatX`	`(value: string \| number \| Date) => string`	Custom x label text.
`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.

Campaign results

Point

Group

Spend

Sign-ups

Reach

Brand search

$4,200

610

18,000

Competitor terms

$9,800

720

22,000

Product search

$14,500

1,380

31,000

Shopping ads

$21,000

1,690

42,000

Generic terms

$27,500

1,540

50,000

Launch video

Social

$6,400

290

64,000

Creator series

Social

$12,800

820

71,000

Carousel ads

Social

$18,200

760

48,000

Story ads

Social

$24,600

1,120

83,000

Lookalike audiences

Social

$33,800

1,470

96,000

Welcome series

$1,800

540

9,000

Newsletter feature

$3,100

460

14,000

Win-back

$5,200

830

12,000

Partner list

$8,600

690

21,000

Data

// One row per point. const campaignResults = [ { campaign: 'Brand search', channel: 'Search', spend: 4200, signups: 610, reach: 18000 }, { campaign: 'Story ads', channel: 'Social', spend: 24600, signups: null, reach: 83000 }, // … ]; <ScatterChartCard title="Campaign results" data={campaignResults} x="spend" // a numeric field: across y="signups" // a numeric field: up, and the headline label="campaign" // a text field that names each point size="reach" // optional: a numeric field for bubble area group="channel" // optional: a text field for color and legend />

<ScatterChartCard title="Campaign results" x="spend" y="signups" label="campaign" ranges={[ { id: 'quarter', label: 'This quarter', data: thisQuarter, delta: 0.198 }, { id: 'last-quarter', label: 'Last quarter', data: lastQuarter, delta: 0.074 }, ]} />

Strip and beeswarm

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'

Resting headline summary; Strip defaults to mean, the others to sum.

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

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.

category

text key of Row

Category lane for each point.

value

numeric key of Row

Measured horizontal position.

label

text key of Row

Unique accessible point name; falls back to row index.

display

'strip' | 'beeswarm'

Stable jitter (default) or collision-free placement.

radius

number

Point radius in pixels, 2–12; default 4.

onKeyDown

KeyboardEventHandler<HTMLElement>

Keyboard handler on the card frame. Chart inspection also has its own keyboard handling.

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.

trails

boolean

Join successive observations within each group. Gaps break trails; duplicate or missing time keys suppress that group’s trail.

trailOrder

numeric key of Row

Explicit numeric time order. Otherwise follows input row order.

data

Row[]

One row per point. Omit when using ranges.

x

numeric key of Row

Places each point across.

y

numeric key of Row

Places each point up, and drives the headline.

label

text key of Row

Names a point when it is read. Unique labels also keep points steady across periods.

size

numeric key of Row

Sizes points by area, turning dots into bubbles.

sizeLabel

string

Names the size measure, e.g. “Reach”.

group

text key of Row

Colors points by group and adds a legend with each group’s value.

xLabel

string

Title for the horizontal axis.

yLabel

string

Title for the vertical axis.

xFormat

Intl.NumberFormatOptions

Formats x values and ticks, e.g. currency or seconds.

trend

boolean

A least-squares line through the points, with its r² in the footer.

aggregate

'sum' | 'mean' | 'max'

How the resting headline sums up every plotted y. Sum by default.

height

number

Plot height in pixels, including the axes. Defaults to 260.

headline

number

Resting headline. Defaults to the aggregate of every plotted y.

delta

number

Fractional change for the chip.

deltaTone

'default' | 'inverse' | 'neutral'

Use inverse when a decrease is good.

range

string

Static period label in the header.

ranges

{ id, label, data, delta?, headline? }[]

Turns the period label into a select. Each range swaps the points.

color

string

Any CSS color for points without a group.

depth

boolean

Draws each point as a lit sphere with a soft contact shadow. Centers and sizes stay exact.

legend

False removes the legend without changing the data. How the group legend lays out: value tiles (default), a compact inline key, list rows, tinted pills, or bars against the largest.

legendSwatch

'square' | 'dot' | 'line'

The mark beside each legend label. Defaults to a rounded square.

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

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

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.

formatX

(value: string | number | Date) => string

Custom x label text.

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.

Chart style

Palette

Theme

Appearance

Reading & motion

Usage

Data

Strip and beeswarm

Props

Chart style

Palette

Theme

Appearance

Reading & motion

Scatter chart

Usage

Data

Strip and beeswarm

Props