Progress

Usage

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

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

<ProgressCard title="Visitors" value={1260} target={2000} />

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. surface="ghost" controls only the visual frame. See Card composition.

Data

Pass the value and the goal as numbers. The header shows the value in your valueFormat, and the ring shows the share of the goal reached. Past the goal the ring stays full and the percentage keeps counting, so 127% reads as 127%.

// Plain numbers: the measured value and the goal, in the same unit.
<ProgressCard title="Visitors" value={1260} target={2000} />

// Not measured yet? null shows a dash and an empty track, never 0%.
<ProgressCard title="Visitors" value={null} target={2000} />

// Summarizing rows yourself is one line.
const visitors = days.reduce((sum, day) => sum + day.visitors, 0);

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

<ProgressCard
  title="Visitors"
  target={2000}
  ranges={[
    { id: 'week', label: 'Last 7 days', value: 1260, delta: 0.052 },
    { id: 'month', label: 'Last 30 days', value: 5480, target: 8000, delta: 0.031 },
  ]}
/>

Goal pacing

Actual revenue meets a supplied plan at an explicit cutoff. Later actual values are excluded. Expected progress interpolates only between adjacent known plan readings. 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 { GoalPacingCard } from '@lilt-ui/charts';

<GoalPacingCard
  title="Quarterly revenue"
  data={quarterlyPace}
  x="day"
  actual="actual"
  expected="expected"
  at={60}
  target={100000}
  valueFormat={{ "style": "currency", "currency": "USD", "maximumFractionDigits": 0 }}
/>

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.
`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.
`x`	`numeric key of Row`	Finite, unique elapsed periods.
`actual`	`numeric keys of Row`	Supplied actual and planned measurements; the chart does not forecast.
`expected`	`numeric keys of Row`	Supplied actual and planned measurements; the chart does not forecast.
`at`	`number`	Current period, supplied explicitly.
`target`	`number`	Positive goal on the same measurement scale.
`onKeyDown`	`KeyboardEventHandler<HTMLElement>`	Keyboard handler on the card frame. Chart inspection also has its own keyboard handling.

Milestone progress

Named checkpoints keep their measured positions along one track. Completed, current, and upcoming states follow the supplied current value; null means unknown. 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 { MilestoneProgressCard } from '@lilt-ui/charts';

<MilestoneProgressCard
  title="Release readiness"
  data={releaseCheckpoints}
  label="name"
  position="position"
  current={68}
  target={100}
/>

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 170px. Dense data may expand within the scrollable viewport.
`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.
`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.
`label`	`text key of Row`	Unique checkpoint name.
`position`	`numeric key of Row`	Unique checkpoint position from zero through target.
`current`	`number \| null`	Current progress, including values beyond the target.
`target`	`number`	Positive track endpoint, default 100.
`onKeyDown`	`KeyboardEventHandler<HTMLElement>`	Keyboard handler on the card frame. Chart inspection also has its own keyboard handling.

Props

Every prop ProgressCard 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.
`value`	`number \| null`	The measured amount. null shows a dash, never zero.
`target`	`number`	The goal, in the value’s unit.
`label`	`string`	Words under the percentage. “of goal” by default.
`variant`	`'ring' \| 'thick' \| 'gauge'`	A thin ring (default), a heavy ring on a soft disc, or a half-ring gauge.
`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, value, target?, delta? }[]`	A period select. Each range brings its own value and, optionally, goal.
`footer`	`ReactNode`	Content under the ring.
`color`	`string`	Any CSS color for the progress.
`depth`	`boolean`	Lights the fill as a tube in a groove cut into the card. The arc keeps its exact angle.
`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.
`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.
`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.

// Plain numbers: the measured value and the goal, in the same unit. <ProgressCard title="Visitors" value={1260} target={2000} /> // Not measured yet? null shows a dash and an empty track, never 0%. <ProgressCard title="Visitors" value={null} target={2000} /> // Summarizing rows yourself is one line. const visitors = days.reduce((sum, day) => sum + day.visitors, 0);

<ProgressCard title="Visitors" target={2000} ranges={[ { id: 'week', label: 'Last 7 days', value: 1260, delta: 0.052 }, { id: 'month', label: 'Last 30 days', value: 5480, target: 8000, delta: 0.031 }, ]} />

Goal pacing

import { GoalPacingCard } from '@lilt-ui/charts'; <GoalPacingCard title="Quarterly revenue" data={quarterlyPace} x="day" actual="actual" expected="expected" at={60} target={100000} valueFormat={{ "style": "currency", "currency": "USD", "maximumFractionDigits": 0 }} />

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.

legend

Legend layout; false hides it. Correlation defaults to false.

legendSwatch

'square' | 'dot' | 'line'

Legend marker, square by default.

x

numeric key of Row

Finite, unique elapsed periods.

actual

numeric keys of Row

Supplied actual and planned measurements; the chart does not forecast.

expected

numeric keys of Row

Supplied actual and planned measurements; the chart does not forecast.

at

number

Current period, supplied explicitly.

target

number

Positive goal on the same measurement scale.

onKeyDown

KeyboardEventHandler<HTMLElement>

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

Milestone progress

import { MilestoneProgressCard } from '@lilt-ui/charts'; <MilestoneProgressCard title="Release readiness" data={releaseCheckpoints} label="name" position="position" current={68} target={100} />

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 170px. Dense data may expand within the scrollable viewport.

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

motion

'auto' | 'none'

None turns off decorative motion; reduced motion does this automatically.

legend

Legend layout; false hides it. Correlation defaults to false.

legendSwatch

'square' | 'dot' | 'line'

Legend marker, square by default.

label

text key of Row

Unique checkpoint name.

position

numeric key of Row

Unique checkpoint position from zero through target.

current

number | null

Current progress, including values beyond the target.

target

number

Positive track endpoint, default 100.

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.

value

number | null

The measured amount. null shows a dash, never zero.

target

number

The goal, in the value’s unit.

label

string

Words under the percentage. “of goal” by default.

variant

'ring' | 'thick' | 'gauge'

A thin ring (default), a heavy ring on a soft disc, or a half-ring gauge.

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, value, target?, delta? }[]

A period select. Each range brings its own value and, optionally, goal.

footer

ReactNode

Content under the ring.

color

string

Any CSS color for the progress.

depth

boolean

Lights the fill as a tube in a groove cut into the card. The arc keeps its exact angle.

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.

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.

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

Goal pacing

Milestone progress

Props

Chart style

Palette

Theme

Appearance

Reading & motion

Progress

Usage

Data

Goal pacing

Milestone progress

Props