Data Display

Timeline

Timestamp-first event rail with grouping, tone markers, and connector continuity.

import { Timeline } from '@lostgradient/cinder/timeline';
timelinehistoryevents
01

Overview

Timestamp-first event rail for workflow events, audit logs, run histories, and grouped temporal sequences. Timeline is not a live region; use Feed for streaming activity that should be announced to assistive technology.

See the chronological display boundary decision for the distinction between Timeline, RunStepTimeline, and Feed.

Usage

svelte 
<script lang="ts">
  import Timeline from '@lostgradient/cinder/timeline';
  import type { TimelineEntry } from '@lostgradient/cinder/timeline';

  const entries: TimelineEntry[] = [
    {
      id: 'created',
      datetime: '2026-05-23T10:00:00Z',
      timestamp: '10:00',
      title: 'Workflow started',
      tone: 'info',
    },
    {
      id: 'completed',
      datetime: '2026-05-23T10:30:00Z',
      timestamp: '10:30',
      title: 'Workflow completed',
      tone: 'success',
    },
  ];
</script>

<Timeline {entries} label="Workflow timeline">
  {#snippet children(entry)}
    {entry.title}
  {/snippet}
</Timeline>

Marker snippets are decorative. Do not place focusable or interactive content inside marker; the marker wrapper is hidden from assistive technology and marked inert.

Live preview
02

When to use

Use when
  • Showing dated workflow, audit, or run-history events on a temporal rail.
Avoid when
  • Surfacing a real-time social or activity stream — feed is the higher-affordance composition.
  • Guiding users through a numbered procedural flow. Use Steps instead
  • Showing async execution state with retries, branches, or progress. Use Run Step Timeline instead
  • Showing a live activity or dense operational stream — use feed (its log arm covers operational streams).
03

Examples

Custom dot styles

A timeline with decorative marker snippets for each tone.

Gap threshold

With `gapThresholdMinutes`, the connector after an entry is hidden when the next entry is more than that many minutes away — visually breaking the line across large time gaps.

Grouped by day

A timeline grouped by UTC day while preserving source order.

Horizontal timeline

A compact horizontal timeline for phase comparisons.

Vertical timeline

A timestamp-first event rail for workflow and audit history.

04

Props

Props for timeline
NameTypeDefaultDescription
entries required TimelineEntry[] Timeline entries rendered in source order.
orientation 'vertical' | 'horizontal' 'vertical' Layout orientation.
groupBy 'none' | 'day' | 'week' 'none' Optional adjacent UTC day/week grouping mode.
weekStartsOn 'sunday' | 'monday' 'monday' Week start used for UTC week grouping.
groupHeaderLevel TimelineHeadingLevel | undefined 3 Heading level applied to rendered group headers.
gapThresholdMinutes number Hide the following connector when adjacent valid timestamps exceed this gap (in minutes).
label text Fallback accessible label used only when aria-label and aria-labelledby are absent.
children Snippet<[TimelineEntry]>undefined Optional per-entry body content.
marker Snippet<[TimelineEntry]>undefined Decorative per-entry marker content. Must not contain interactive descendants.