Timeline

A composable timeline component for displaying chronological events with multiple layout positions, marker variants, and custom icons.

View Markdown

Default

  1. v1.0.0 Released

    Initial stable release with core components and documentation.

  2. v1.1.0 Released

    Added Timeline, Empty, and DatePicker components.

  3. v1.2.0 In Progress

    Working on data table improvements and new chart components.

  4. v2.0.0 Planned

    Major update with design system overhaul and accessibility improvements.

Variants

  1. Default

    Neutral marker for standard events.

  2. Primary

    Highlighted marker for key events.

  3. Success

    Indicates a completed or successful event.

  4. Warning

    Highlights an event that needs attention.

  5. Destructive

    Signals an error or critical event.

With Icons

  1. Pull Request Opened

    feat: add timeline component (#142)

  2. Code Review

    2 comments from reviewers on styling approach.

  3. CI Failed

    Lint check failed due to unused import.

  4. Changes Requested

    Reviewer requested minor refactoring of utility functions.

  5. Merged

    All checks passed. Merged into main by @developer.

With Custom Marker

  1. MJ

    Marcus Johnson merged a pull request

    Refactored authentication module to support OAuth 2.0 providers.

  2. SC

    Sarah Chen commented on an issue

    Suggested a fix for the date picker timezone handling.

  3. AR

    Alex Rivera opened a pull request

    Added new chart components with responsive breakpoints.

  4. EP

    Emma Patel deployed to production

    Released v1.4.2 with accessibility improvements across all form components.

Right Aligned

  1. Deployment Successful

    Production build deployed to all regions.

  2. Tests Passed

    All 142 integration tests passed successfully.

  3. Build Started

    CI pipeline triggered by merge to main branch.

Alternate

  1. Application Submitted

    Your application was received and is under review.

  2. Phone Screen

    Initial call with the recruiting team completed.

  3. Technical Interview

    Passed the technical assessment with positive feedback.

  4. Final Round

    On-site interviews with the engineering team scheduled.

  5. Offer Extended

    Congratulations! An offer letter has been sent.

Center

  1. Company Founded

    Started with a small team of three in a garage.

  2. Series A Funding

    Raised $5M to scale the product and grow the team.

  3. 100K Users

    Reached the first major milestone in user adoption.

  4. Global Expansion

    Launched in 12 new markets across Europe and Asia.

API Reference

TimelineRoot

Root container rendered as a semantic ordered list. Provides layout context to all child items.

PropTypeDefaultDescription
position'left' | 'right' | 'alternate' | 'center''left'Controls the layout of content relative to the marker line. Left and right place all content on one side. Alternate switches sides for each item. Center uses a grid layout with content on both sides.
classNamestring-Additional CSS classes for the root ordered list
...propsReact.ComponentProps<"ol">-Standard ordered list element props

TimelineItem

Individual timeline entry rendered as a list item. Automatically receives position and index context from the parent TimelineRoot.

PropTypeDefaultDescription
classNamestring-Additional CSS classes for the list item
...propsReact.ComponentProps<"li">-Standard list item element props

TimelineMarker

Visual indicator on the timeline line. Renders a colored dot by default, a custom icon, or fully custom content such as an avatar when children are provided.

PropTypeDefaultDescription
childrenReact.ReactNode-Custom content to render instead of the default dot or icon. When provided, variant and icon props are ignored and no default styling is applied to the marker.
variant'default' | 'primary' | 'success' | 'warning' | 'destructive''default'Color variant of the marker circle. Ignored when children are provided.
iconReact.ReactNode-Custom icon to display inside the marker instead of the default dot. Ignored when children are provided.
classNamestring-Additional CSS classes for the marker element
...propsReact.ComponentProps<"div">-Standard div element props

TimelineContent

Wrapper for the main content of a timeline entry. Handles text alignment and spacing based on the timeline position.

PropTypeDefaultDescription
classNamestring-Additional CSS classes for the content wrapper
...propsReact.ComponentProps<"div">-Standard div element props

TimelineSpacer

Empty flex spacer used with alternate and center positions to fill the opposite side of content.

PropTypeDefaultDescription
classNamestring-Additional CSS classes for the spacer element
...propsReact.ComponentProps<"div">-Standard div element props

TimelineTitle

Bold title text for a timeline entry. Rendered as a paragraph element with semibold font weight.

PropTypeDefaultDescription
classNamestring-Additional CSS classes for the title
...propsReact.ComponentProps<"p">-Standard paragraph element props

TimelineDescription

Secondary descriptive text for a timeline entry. Rendered in a smaller, muted style.

PropTypeDefaultDescription
classNamestring-Additional CSS classes for the description
...propsReact.ComponentProps<"p">-Standard paragraph element props

TimelineTime

Semantic time element for displaying timestamps. Supports the native dateTime attribute for machine-readable values.

PropTypeDefaultDescription
dateTimestring-Machine-readable date/time value for accessibility and SEO
classNamestring-Additional CSS classes for the time element
...propsReact.ComponentProps<"time">-Standard time element props