Activity ring

83peak · 14:40

No bucket selected.

36 cyclic positions; missing observations are distinct from zero.

Busiest · 14:4083Quietest · 04:407

Usage

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

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

<ActivityRingCard
  title="Request rhythm"
  data={requestRhythm}
  hour="hour"
  value="requests"
  bucketMinutes={40}
/>

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

Each row is one time slot: hour places it around the day, clockwise from midnight at the top, and value fills its dots; TypeScript rejects anything but numeric fields. Every time must fall on a bucketMinutes slot, once. Dots fill against maximum, which defaults to a round number above the peak. A slot that is null, or has no row, stays empty and is counted in the footer, while a measured zero shows as a real reading, so an outage never looks like a quiet hour. The headline totals the day; aggregate switches it to the average or the peak.

// One row per time slot; hour is the time of day, so 14.5 is 14:30.
const requestRhythm = [
  { hour: 0, requests: 14 },
  { hour: 0.6667, requests: 20 },   // 00:40
  { hour: 2.6667, requests: null }, // not recorded
  // …
];

<ActivityRingCard
  title="Request rhythm"
  data={requestRhythm}
  hour="hour"        // a numeric field: hours from 0 up to 24
  value="requests"   // a numeric field
  bucketMinutes={40} // minutes per slot; must divide a day
/>

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

<ActivityRingCard
  title="Request rhythm"
  hour="hour"
  value="requests"
  bucketMinutes={40}
  ranges={[
    { id: 'today', label: 'Today', data: today, delta: 0.186 },
    { id: 'yesterday', label: 'Yesterday', data: yesterday, delta: -0.034 },
  ]}
/>

Props

Every prop ActivityRingCard 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.
`data`	`Row[]`	One row per time slot. Omit when using ranges.
`hour`	`numeric key of Row`	Time of day in hours, from 0 up to 24; 14.5 is 14:30.
`value`	`numeric key of Row`	How much happened in the slot. `null` means not recorded.
`bucketMinutes`	`number`	Minutes per slot. Must divide a day, like 15, 30, 40, or 60. Defaults to 60.
`unit`	`string`	What `value` counts, e.g. “requests”. Defaults to the field name.
`maximum`	`number`	Value that fills a slot’s dots. Defaults to a round number above the peak.
`aggregate`	`'sum' \| 'mean' \| 'max'`	How the resting headline sums up the day. Sum by default.
`height`	`number`	Ring height in pixels, at least 180. Defaults to 280.
`headline`	`number`	Resting headline. Defaults to the aggregate of every recorded slot.
`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 day.
`color`	`string`	Any CSS color for the dots.
`depth`	`boolean`	Turns each dot into a small lit puck.
`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.
`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.

Data

// One row per time slot; hour is the time of day, so 14.5 is 14:30. const requestRhythm = [ { hour: 0, requests: 14 }, { hour: 0.6667, requests: 20 }, // 00:40 { hour: 2.6667, requests: null }, // not recorded // … ]; <ActivityRingCard title="Request rhythm" data={requestRhythm} hour="hour" // a numeric field: hours from 0 up to 24 value="requests" // a numeric field bucketMinutes={40} // minutes per slot; must divide a day />

<ActivityRingCard title="Request rhythm" hour="hour" value="requests" bucketMinutes={40} ranges={[ { id: 'today', label: 'Today', data: today, delta: 0.186 }, { id: 'yesterday', label: 'Yesterday', data: yesterday, delta: -0.034 }, ]} />

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 time slot. Omit when using ranges.

hour

numeric key of Row

Time of day in hours, from 0 up to 24; 14.5 is 14:30.

value

numeric key of Row

How much happened in the slot. `null` means not recorded.

bucketMinutes

number

Minutes per slot. Must divide a day, like 15, 30, 40, or 60. Defaults to 60.

unit

string

What `value` counts, e.g. “requests”. Defaults to the field name.

maximum

number

Value that fills a slot’s dots. Defaults to a round number above the peak.

aggregate

'sum' | 'mean' | 'max'

How the resting headline sums up the day. Sum by default.

height

number

Ring height in pixels, at least 180. Defaults to 280.

headline

number

Resting headline. Defaults to the aggregate of every recorded slot.

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 day.

color

string

Any CSS color for the dots.

depth

boolean

Turns each dot into a small lit puck.

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.

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

Props

Chart style

Palette

Theme

Appearance

Reading & motion

Activity ring

Usage

Data

Props