Timeline

Vertical or horizontal sequence of events with dots, connectors, and per-event colour and icon options.

stable
since v0.1.0
2.2 kB
data-display
timeline
activity

Preview

tsx

import {
  Timeline,
  TimelineConnector,
  TimelineContent,
  TimelineDot,
  TimelineItem,
  TimelineSeparator,
} from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <Timeline>
      <TimelineItem>
        <TimelineSeparator>
          <TimelineDot />
          <TimelineConnector />
        </TimelineSeparator>
        <TimelineContent>
          <strong>Signed up</strong>
          <div style={{ color: 'var(--cynosure-color-fg-muted)', fontSize: '0.875rem' }}>
            Jan 14, 2024
          </div>
        </TimelineContent>
      </TimelineItem>
      <TimelineItem>
        <TimelineSeparator>
          <TimelineDot />
          <TimelineConnector />
        </TimelineSeparator>
        <TimelineContent>
          <strong>Upgraded to Pro</strong>
          <div style={{ color: 'var(--cynosure-color-fg-muted)', fontSize: '0.875rem' }}>
            Feb 02, 2024
          </div>
        </TimelineContent>
      </TimelineItem>
      <TimelineItem>
        <TimelineSeparator>
          <TimelineDot />
        </TimelineSeparator>
        <TimelineContent>
          <strong>Invited team</strong>
          <div style={{ color: 'var(--cynosure-color-fg-muted)', fontSize: '0.875rem' }}>
            Mar 18, 2024
          </div>
        </TimelineContent>
      </TimelineItem>
    </Timeline>
  );
}

Sizes

Three sizes are available: sm, md (default), and lg.

Preview

Open

tsx

import {
  Timeline,
  TimelineConnector,
  TimelineContent,
  TimelineDot,
  TimelineItem,
  TimelineSeparator,
} from '@arshad-shah/cynosure-react';

function Sample({ size }: { size: 'sm' | 'md' | 'lg' }) {
  return (
    <Timeline size={size}>
      <TimelineItem>
        <TimelineSeparator>
          <TimelineDot />
          <TimelineConnector />
        </TimelineSeparator>
        <TimelineContent>
          <strong>Created</strong>
        </TimelineContent>
      </TimelineItem>
      <TimelineItem>
        <TimelineSeparator>
          <TimelineDot />
        </TimelineSeparator>
        <TimelineContent>
          <strong>Shipped</strong>
        </TimelineContent>
      </TimelineItem>
    </Timeline>
  );
}

export default function Example() {
  return (
    <div style={{ display: 'flex', gap: '2rem', alignItems: 'flex-start' }}>
      <Sample size="sm" />
      <Sample size="md" />
      <Sample size="lg" />
    </div>
  );
}

Color schemes

Each TimelineDot accepts a colorScheme — accent, neutral, success, warning, danger, or info — to signal event semantics.

Preview

Open

tsx

import {
  Timeline,
  TimelineConnector,
  TimelineContent,
  TimelineDot,
  TimelineItem,
  TimelineSeparator,
} from '@arshad-shah/cynosure-react';

const events = [
  { color: 'success', label: 'Build succeeded', time: '10:14' },
  { color: 'info', label: 'Deploy started', time: '10:14' },
  { color: 'warning', label: 'Slow database query', time: '10:17' },
  { color: 'danger', label: 'Health check failed', time: '10:19' },
] as const;

export default function Example() {
  return (
    <Timeline>
      {events.map((event, idx) => (
        <TimelineItem key={event.label}>
          <TimelineSeparator>
            <TimelineDot colorScheme={event.color} />
            {idx < events.length - 1 ? <TimelineConnector /> : null}
          </TimelineSeparator>
          <TimelineContent>
            <strong>{event.label}</strong>
            <div style={{ color: 'var(--cynosure-color-fg-muted)', fontSize: '0.875rem' }}>
              {event.time}
            </div>
          </TimelineContent>
        </TimelineItem>
      ))}
    </Timeline>
  );
}

With custom icons

Pass icon (or children) to TimelineDot to render a glyph inside the marker.

Preview

Open

tsx

import {
  Timeline,
  TimelineConnector,
  TimelineContent,
  TimelineDot,
  TimelineItem,
  TimelineSeparator,
} from '@arshad-shah/cynosure-react';

const IconCheck = () => (
  <svg
    width="12"
    height="12"
    viewBox="0 0 24 24"
    fill="none"
    stroke="currentColor"
    strokeWidth="2.5"
    strokeLinecap="round"
    strokeLinejoin="round"
    aria-hidden="true"
  >
    <polyline points="20 6 9 17 4 12" />
  </svg>
);

const IconDot = () => (
  <svg width="10" height="10" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
    <circle cx="12" cy="12" r="6" />
  </svg>
);

export default function Example() {
  return (
    <Timeline>
      <TimelineItem>
        <TimelineSeparator>
          <TimelineDot colorScheme="success" icon={<IconCheck />} />
          <TimelineConnector />
        </TimelineSeparator>
        <TimelineContent>
          <strong>Deployed v1.0</strong>
          <div style={{ color: 'var(--cynosure-color-fg-muted)', fontSize: '0.875rem' }}>
            10 minutes ago
          </div>
        </TimelineContent>
      </TimelineItem>
      <TimelineItem>
        <TimelineSeparator>
          <TimelineDot colorScheme="accent" icon={<IconDot />} variant="outline" />
        </TimelineSeparator>
        <TimelineContent>
          <strong>Preparing v1.1</strong>
          <div style={{ color: 'var(--cynosure-color-fg-muted)', fontSize: '0.875rem' }}>
            in progress
          </div>
        </TimelineContent>
      </TimelineItem>
    </Timeline>
  );
}

Horizontal orientation

Pass orientation="horizontal" for a step-tracker layout — connectors run left-to-right and items wrap onto multiple lines when narrow.

Preview

Open

tsx

import {
  Timeline,
  TimelineConnector,
  TimelineContent,
  TimelineDot,
  TimelineItem,
  TimelineSeparator,
} from '@arshad-shah/cynosure-react';

const steps = ['Account', 'Profile', 'Workspace', 'Done'];

export default function Example() {
  return (
    <Timeline orientation="horizontal">
      {steps.map((label, idx) => (
        <TimelineItem key={label}>
          <TimelineSeparator>
            <TimelineDot
              colorScheme={idx <= 1 ? 'success' : 'accent'}
              variant={idx <= 1 ? 'solid' : 'outline'}
            />
            {idx < steps.length - 1 ? <TimelineConnector /> : null}
          </TimelineSeparator>
          <TimelineContent>
            <strong>{label}</strong>
          </TimelineContent>
        </TimelineItem>
      ))}
    </Timeline>
  );
}

API

PropTypeDefaultDescription

orientation

"vertical"|"horizontal"

vertical

Lay items out vertically (top-to-bottom) or horizontally (left-to-right).

size

"sm"|"md"|"lg"

Density preset for dot size, gap, and connector thickness.

Accessibility

Renders as a semantic <ol> so screen readers announce position and total count.
Each TimelineItem is an <li>; the last item carries data-last="true" so the trailing connector can be hidden.
TimelineSeparator, TimelineDot, and TimelineConnector are aria-hidden — they’re purely decorative.
Provide a heading or aria-label on the <Timeline> itself when its purpose isn’t clear from surrounding context.
Colour is never the sole carrier of meaning — pair colorScheme with a textual cue in TimelineContent.

Recipes

Switch orientation to "horizontal" for onboarding step trackers and progress checklists.
Use TimelineDot variant="outline" for “pending” events; variant="solid" for completed ones.
Pass an icon to TimelineDot (e.g. a checkmark SVG) to signal event type at a glance.
Compose TimelineContent with Card or Stat for dense activity feeds.