Data Display

Timeline

Timestamp-first event rail that renders workflow, audit, or run-history entries 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.

Usage

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

  const entries = [
    {
      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
  • Visualizing an ordered sequence of dated events with a temporal rail, timestamp labels, grouping headers, and marker tones.
  • Displaying workflow steps, audit logs, or run histories where each entry needs connector continuity or gap breaks.
Avoid when
  • Surfacing a real-time social or activity stream — feed is the higher-affordance composition.
  • Guiding users through a numbered procedural flow — steps conveys progress more clearly.
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
Name Type Default Required Bindable Description
entries TimelineEntry[] req Timeline entries rendered in source order.
orientation TimelineOrientation | undefined 'vertical' Layout orientation.
groupBy TimelineGroupBy | undefined 'none' Optional adjacent UTC day/week grouping mode.
weekStartsOn TimelineWeekStartsOn | undefined 'monday' Week start used for UTC week grouping.
groupHeaderLevel TimelineHeadingLevel | undefined 3 Heading level applied to rendered group headers.
gapThresholdMinutes number | undefined Hide the following connector when adjacent valid timestamps exceed this gap (in minutes).
label string | undefined 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.
role unknown req