Event helix

One turn per UTC day · Time rises from bottom to top · Larger beads: larger events

Service activity
Observation	Value
Run 01 · 2026-09-28 02:00 UTC	12
Run 02 · 2026-09-28 06:00 UTC	29
Run 03 · 2026-09-28 09:00 UTC	46
Run 04 · 2026-09-28 12:00 UTC	63
Run 05 · 2026-09-28 16:00 UTC	80
Run 06 · 2026-09-28 21:00 UTC	17
Run 07 · 2026-09-29 02:00 UTC	34
Run 08 · 2026-09-29 06:00 UTC	51
Run 09 · 2026-09-29 09:00 UTC	68
Run 10 · 2026-09-29 12:00 UTC	85
Run 11 · 2026-09-29 16:00 UTC	22
Run 12 · 2026-09-29 21:00 UTC	39
Run 13 · 2026-09-30 02:00 UTC	56
Run 14 · 2026-09-30 06:00 UTC	73
Run 15 · 2026-09-30 09:00 UTC	90
Run 16 · 2026-09-30 12:00 UTC	27
Run 17 · 2026-09-30 16:00 UTC	44
Run 18 · 2026-09-30 21:00 UTC	61
Run 19 · 2026-10-01 02:00 UTC	78
Run 20 · 2026-10-01 06:00 UTC	15
Run 21 · 2026-10-01 09:00 UTC	32
Run 22 · 2026-10-01 12:00 UTC	49
Run 23 · 2026-10-01 16:00 UTC	66
Run 24 · 2026-10-01 21:00 UTC	83
Run 25 · 2026-10-02 02:00 UTC	20
Run 26 · 2026-10-02 06:00 UTC	37
Run 27 · 2026-10-02 09:00 UTC	54
Run 28 · 2026-10-02 12:00 UTC	71
Run 29 · 2026-10-02 16:00 UTC	88
Run 30 · 2026-10-02 21:00 UTC	25

Usage

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

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

<EventHelixCard title="Service activity" data={serviceEvents} label="event" date="at" value="requests" group="service" />

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 event has a unique label, timestamp and nonnegative magnitude. Dates accept Date objects, epoch milliseconds or ISO strings with explicit time zones (plain ISO dates are UTC). Events are sorted chronologically; simultaneous events remain individually keyboard-accessible. Daily turns start at UTC midnight; weekly turns start Monday. At most 60 cycles fit one view. Null magnitudes stay marked as missing; zero is a small measured bead.

const serviceEvents = [
  { event: 'Run 01', at: '2026-09-28T02:00:00Z', service: 'API', requests: 12 },
  { event: 'Run 02', at: '2026-09-28T06:00:00Z', service: 'Workers', requests: 29 },
];

Props

Every prop EventHelixCard 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 observation. Omit when using ranges.
`height`	`number`	Minimum plot height, default 360. Dense data can expand or scroll to preserve geometry.
`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.
`label`	`text key of Row`	Unique event name.
`date`	`date, string, or numeric key of Row`	Event timestamp, interpreted in UTC.
`value`	`numeric key of Row`	Nonnegative magnitude, encoded by bead size.
`group`	`text key of Row`	Optional category color and legend.
`cycle`	`'day' \| 'week'`	One revolution per day (default) or week.
`pitch`	`number`	Minimum turn spacing, 26 to 100 pixels, default 54.
`legend`	`false \| 'tiles' \| 'inline' \| 'list' \| 'pills' \| 'bars'`	Rounded-square legend with group inspection and pinning. Defaults to tiles; false removes it.
`onKeyDown`	`KeyboardEventHandler<HTMLElement>`	Keyboard handler on the card frame. Chart inspection also has its own keyboard handling.
`legendSwatch`	`'square' \| 'dot' \| 'line'`	Marker beside each group label, where a group legend is present. Defaults to square.

Service activity

Observation

Value

Run 01 · 2026-09-28 02:00 UTC

Run 02 · 2026-09-28 06:00 UTC

Run 03 · 2026-09-28 09:00 UTC

Run 04 · 2026-09-28 12:00 UTC

Run 05 · 2026-09-28 16:00 UTC

Run 06 · 2026-09-28 21:00 UTC

Run 07 · 2026-09-29 02:00 UTC

Run 08 · 2026-09-29 06:00 UTC

Run 09 · 2026-09-29 09:00 UTC

Run 10 · 2026-09-29 12:00 UTC

Run 11 · 2026-09-29 16:00 UTC

Run 12 · 2026-09-29 21:00 UTC

Run 13 · 2026-09-30 02:00 UTC

Run 14 · 2026-09-30 06:00 UTC

Run 15 · 2026-09-30 09:00 UTC

Run 16 · 2026-09-30 12:00 UTC

Run 17 · 2026-09-30 16:00 UTC

Run 18 · 2026-09-30 21:00 UTC

Run 19 · 2026-10-01 02:00 UTC

Run 20 · 2026-10-01 06:00 UTC

Run 21 · 2026-10-01 09:00 UTC

Run 22 · 2026-10-01 12:00 UTC

Run 23 · 2026-10-01 16:00 UTC

Run 24 · 2026-10-01 21:00 UTC

Run 25 · 2026-10-02 02:00 UTC

Run 26 · 2026-10-02 06:00 UTC

Run 27 · 2026-10-02 09:00 UTC

Run 28 · 2026-10-02 12:00 UTC

Run 29 · 2026-10-02 16:00 UTC

Run 30 · 2026-10-02 21:00 UTC

Data

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 360. Dense data can expand or scroll to preserve geometry.

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.

label

text key of Row

Unique event name.

date

date, string, or numeric key of Row

Event timestamp, interpreted in UTC.

value

numeric key of Row

Nonnegative magnitude, encoded by bead size.

group

text key of Row

Optional category color and legend.

cycle

'day' | 'week'

One revolution per day (default) or week.

pitch

number

Minimum turn spacing, 26 to 100 pixels, default 54.

legend

Rounded-square legend with group inspection and pinning. Defaults to tiles; false removes it.

onKeyDown

KeyboardEventHandler<HTMLElement>

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

legendSwatch

'square' | 'dot' | 'line'

Marker beside each group label, where a group legend is present. Defaults to square.

Chart style

Palette

Theme

Appearance

Reading & motion

Usage

Data

Props

Chart style

Palette

Theme

Appearance

Reading & motion

Event helix

Usage

Data

Props