Font Awesome Build Awesome
Search ⌘KCtrl+K
Light Dark System Docs Color Scheme: System \ Default Awesome Shoelace Active Brutalist Glossy Matter Mellow Playful Premium Tailspin Docs Theme: Default Icon Style: Classic Regular
Solid Regular Light Thin Classic Sharp Duotone Sharp Duotone
Docs Most styles require Font Awesome Pro.
Server-Side Rendering: Off Server-Side Rendering Docs
View on GitHub
Start Components Docs Help Pro
Login Log into your account
Web Awesome Font Awesome Build Awesome
Search this site… /
Light Dark System Docs Color Scheme: System \ Default Awesome Shoelace Active Brutalist Glossy Matter Mellow Playful Premium Tailspin Docs Theme: Default Icon Style: Classic Regular
Solid Regular Light Thin Classic Sharp Duotone Sharp Duotone
Docs Most styles require Font Awesome Pro.
Server-Side Rendering: Off Server-Side Rendering Docs
View on GitHub
Components Pro

Getting Started

  • Installation
  • Usage
  • Forms
  • Localization
  • Frameworks
  • Using with AI
  • Figma Design Kit ProThis requires access to Web Awesome Pro
  • Server Rendering

Resources

  • Accessibility
  • Browser Support
  • Contributing
  • Patterns ProPatterns require access to Web Awesome Pro
  • Migrating from Shoelace
  • Visual Tests
  • Changelog
  • Help & Support

Theming & Utilities

  • Overview
  • Built-in Themes
  • Color Palettes
  • Design Tokens
  • Customizing & Theming
  • CSS Utilities

Actions

  • Button
  • Button Group
  • Copy Button
  • Dropdown
    • Dropdown Item

Forms

  • Checkbox
  • Checkbox Group
  • Color Picker
  • Combobox ProThis requires access to Web Awesome Pro
  • Date Input ProThis requires access to Web Awesome Pro
  • Date Picker ProThis requires access to Web Awesome Pro
  • File Input ProThis requires access to Web Awesome Pro
  • Input
  • Known Date
  • Number Input
  • OTP Input
  • Radio Group
    • Radio
  • Rating
  • Rich Text Editor ProThis requires access to Web Awesome Pro
  • Select
    • Option
  • Slider
  • Switch
  • Tag Input
  • Textarea
  • Time Input

Layout

  • Accordion
    • Accordion Item
  • Card
  • Details
  • Dialog
  • Divider
  • Drawer
  • Page
  • Scroller
  • Split Panel
  • Timeline
    • Timeline Item

Navigation

  • Breadcrumb
    • Breadcrumb Item
  • Pagination
  • Stepper
    • Step
  • Tab Group
    • Tab
    • Tab Panel
  • Tree
    • Tree Item

Feedback

  • Badge
  • Callout
  • Progress Bar
  • Progress Ring
  • Skeleton
  • Spinner
  • Tag
  • Toast
    • Toast Item
  • Tooltip

Media

  • Animated Image
  • Avatar
  • Carousel
    • Carousel Item
  • Code Highlighter
  • Comparison
  • Icon
  • Lightbox
    • Lightbox Item
  • Markdown
  • QR Code
  • Video ProThis requires access to Web Awesome Pro
  • Video Playlist ProThis requires access to Web Awesome Pro
  • Zoomable Frame

Data Viz ProThis requires access to Web Awesome Pro

  • Bar Chart
  • Bubble Chart
  • Data Grid
  • Doughnut Chart
  • Line Chart
  • Pie Chart
  • Polar Area Chart
  • Radar Chart
  • Scatter Chart
  • Sparkline
  • Advanced Usage

Helpers

  • Animation
  • Counter
  • Format Bytes
  • Format Date
  • Format Number
  • Include
  • Intersection Observer
  • Mutation Observer
  • Number Ticker
  • Popover
  • Popup
  • Random Content
  • Relative Time
  • Resize Observer

Timeline

  • Examples
  • Opposite Content
  • Custom Icon
  • Variant
  • Size
  • Orientation
  • Marker Placement
  • Marker Alignment
  • Providing Content
  • Grouping Entries
  • Adding Entries
  • Customizing
  • Accessibility Considerations
  • API
  • Importing
  • Slots
  • Attributes & Properties
  • CSS Custom Properties
  • Custom States
  • CSS Parts
  • Dependencies
  • SSR
On This Page...
  • Examples
  • Opposite Content
  • Custom Icon
  • Variant
  • Size
  • Orientation
  • Marker Placement
  • Marker Alignment
  • Providing Content
  • Grouping Entries
  • Adding Entries
  • Customizing
  • Accessibility Considerations
  • API
  • Importing
  • Slots
  • Attributes & Properties
  • CSS Custom Properties
  • Custom States
  • CSS Parts
  • Dependencies
  • SSR

Timeline

<wa-timeline>
Experimental Layout Since 3.16

Timelines lay out a chronological list of events, such as an order history, activity feed, or changelog.

Order placed

We received your order and will begin processing it shortly.

Order shipped

Your package left the warehouse and is on its way.

Out for delivery

Your package is on the truck and should arrive today.

<wa-timeline label="Order history">
  <wa-timeline-item>
    <wa-format-date slot="opposite" date="2026-07-22T09:00:00" month="short" day="numeric"></wa-format-date>
    <span class="wa-heading-m">Order placed</span>
    <p>We received your order and will begin processing it shortly.</p>
  </wa-timeline-item>
  <wa-timeline-item>
    <wa-format-date slot="opposite" date="2026-07-23T09:00:00" month="short" day="numeric"></wa-format-date>
    <span class="wa-heading-m">Order shipped</span>
    <p>Your package left the warehouse and is on its way.</p>
  </wa-timeline-item>
  <wa-timeline-item variant="brand">
    <wa-format-date slot="opposite" date="2026-07-24T09:00:00" month="short" day="numeric"></wa-format-date>
    <span class="wa-heading-m">Out for delivery</span>
    <p>Your package is on the truck and should arrive today.</p>
  </wa-timeline-item>
</wa-timeline>

Each entry is a <wa-timeline-item>.

Showing progress through a process?
Use <wa-stepper> instead. A timeline is a record of what happened, with no current step.

Examples

Link to This Section

Opposite Content

Link to This Section

Add content to an item's opposite slot to show it on the other side of the rail from the main content, such as a date from <wa-format-date> or <wa-relative-time>.

Launch

Saturn V lifts off from Kennedy Space Center.

Translunar injection

The third stage fires again and Apollo 11 leaves Earth orbit.

Lunar landing

Eagle touches down in the Sea of Tranquility.

First step

One small step.

Splashdown

Columbia lands in the Pacific, southwest of Hawaii.

<wa-timeline>
  <wa-timeline-item>
    <wa-format-date
      slot="opposite"
      date="1969-07-16T13:32:00Z"
      month="short"
      day="numeric"
      hour="numeric"
      minute="numeric"
    ></wa-format-date>
    <span class="wa-heading-m">Launch</span>
    <p>Saturn V lifts off from Kennedy Space Center.</p>
  </wa-timeline-item>
  <wa-timeline-item>
    <wa-format-date
      slot="opposite"
      date="1969-07-16T16:22:00Z"
      month="short"
      day="numeric"
      hour="numeric"
      minute="numeric"
    ></wa-format-date>
    <span class="wa-heading-m">Translunar injection</span>
    <p>The third stage fires again and Apollo 11 leaves Earth orbit.</p>
  </wa-timeline-item>
  <wa-timeline-item>
    <wa-format-date
      slot="opposite"
      date="1969-07-20T20:17:00Z"
      month="short"
      day="numeric"
      hour="numeric"
      minute="numeric"
    ></wa-format-date>
    <span class="wa-heading-m">Lunar landing</span>
    <p>Eagle touches down in the Sea of Tranquility.</p>
  </wa-timeline-item>
  <wa-timeline-item>
    <wa-format-date
      slot="opposite"
      date="1969-07-21T02:56:00Z"
      month="short"
      day="numeric"
      hour="numeric"
      minute="numeric"
    ></wa-format-date>
    <span class="wa-heading-m">First step</span>
    <p>One small step.</p>
  </wa-timeline-item>
  <wa-timeline-item>
    <wa-format-date
      slot="opposite"
      date="1969-07-24T16:50:00Z"
      month="short"
      day="numeric"
      hour="numeric"
      minute="numeric"
    ></wa-format-date>
    <span class="wa-heading-m">Splashdown</span>
    <p>Columbia lands in the Pacific, southwest of Hawaii.</p>
  </wa-timeline-item>
</wa-timeline>

Rendering on the server? Add the with-opposite attribute to each item that has opposite content.
The opposite column is shown once the item hydrates; with-opposite lays it out in the server-rendered markup. See Server-Side Rendering.

Custom Icon

Link to This Section

Use the icon slot on an item to show an element, such as <wa-icon> or an avatar, inside its marker. The icon takes the foreground color that matches the marker's variant. A marker with something in its icon slot is 2em instead of 1em. Resize it with --icon-marker-size, not --marker-size.

The call

A stranger arrives with a map and a warning.

The ordeal

The mountain is not as empty as promised.

The return

Home again, with a story nobody believes.

<wa-timeline>
  <wa-timeline-item variant="warning">
    <wa-icon slot="icon" name="hat-wizard"></wa-icon>
    <span class="wa-heading-m">The call</span>
    <p>A stranger arrives with a map and a warning.</p>
  </wa-timeline-item>
  <wa-timeline-item variant="danger">
    <wa-icon slot="icon" name="dragon"></wa-icon>
    <span class="wa-heading-m">The ordeal</span>
    <p>The mountain is not as empty as promised.</p>
  </wa-timeline-item>
  <wa-timeline-item variant="success">
    <wa-icon slot="icon" name="crown"></wa-icon>
    <span class="wa-heading-m">The return</span>
    <p>Home again, with a story nobody believes.</p>
  </wa-timeline-item>
</wa-timeline>

Rendering on the server? Add the with-icon attribute to each item with content in its icon slot.
The marker is sized up once the item hydrates; with-icon sizes it in the server-rendered markup. See Server-Side Rendering.

Variant

Link to This Section

Set the variant attribute on an item to color its marker with a semantic color. The default is neutral, whose marker stays quiet so the other variants stand out against it.

Neutral Brand Success Warning Danger
<wa-timeline>
  <wa-timeline-item variant="neutral">
    <span class="wa-heading-m">Neutral</span>
  </wa-timeline-item>
  <wa-timeline-item variant="brand">
    <span class="wa-heading-m">Brand</span>
  </wa-timeline-item>
  <wa-timeline-item variant="success">
    <span class="wa-heading-m">Success</span>
  </wa-timeline-item>
  <wa-timeline-item variant="warning">
    <span class="wa-heading-m">Warning</span>
  </wa-timeline-item>
  <wa-timeline-item variant="danger">
    <span class="wa-heading-m">Danger</span>
  </wa-timeline-item>
</wa-timeline>

To flag something that failed or needs attention, pair the variant with an icon in the icon slot and state the reason in the content, so the meaning doesn't depend on color alone.

Build passed Tests passed Deploy failed

Health check timed out after 30 seconds.

<wa-timeline>
  <wa-timeline-item variant="success">
    <wa-icon slot="icon" name="check"></wa-icon>
    <span class="wa-heading-m">Build passed</span>
  </wa-timeline-item>
  <wa-timeline-item variant="success">
    <wa-icon slot="icon" name="check"></wa-icon>
    <span class="wa-heading-m">Tests passed</span>
  </wa-timeline-item>
  <wa-timeline-item variant="danger">
    <wa-icon slot="icon" name="xmark"></wa-icon>
    <span class="wa-heading-m">Deploy failed</span>
    <p>Health check timed out after 30 seconds.</p>
  </wa-timeline-item>
</wa-timeline>

Size

Link to This Section

A timeline is sized relative to the current font size, like a badge. Set font-size on the timeline (or an ancestor element) to change it; markers and text scale together. The connector's thickness and the space between items come from the --connector-width and --gap custom properties, which don't follow the font size.

Extra Small Shipped Small Shipped Medium Shipped Large Shipped Extra Large Shipped
<div class="wa-stack wa-gap-l">
  <wa-timeline style="font-size: var(--wa-font-size-xs);">
    <wa-timeline-item>Extra Small</wa-timeline-item>
    <wa-timeline-item>Shipped</wa-timeline-item>
  </wa-timeline>
  <wa-timeline style="font-size: var(--wa-font-size-s);">
    <wa-timeline-item>Small</wa-timeline-item>
    <wa-timeline-item>Shipped</wa-timeline-item>
  </wa-timeline>
  <wa-timeline style="font-size: var(--wa-font-size-m);">
    <wa-timeline-item>Medium</wa-timeline-item>
    <wa-timeline-item>Shipped</wa-timeline-item>
  </wa-timeline>
  <wa-timeline style="font-size: var(--wa-font-size-l);">
    <wa-timeline-item>Large</wa-timeline-item>
    <wa-timeline-item>Shipped</wa-timeline-item>
  </wa-timeline>
  <wa-timeline style="font-size: var(--wa-font-size-xl);">
    <wa-timeline-item>Extra Large</wa-timeline-item>
    <wa-timeline-item>Shipped</wa-timeline-item>
  </wa-timeline>
</div>

Orientation

Link to This Section

Set the orientation attribute to horizontal to lay items out in a row instead of a column.

Ordered Shipped Delivered
<wa-timeline orientation="horizontal">
  <wa-timeline-item>Ordered</wa-timeline-item>
  <wa-timeline-item>Shipped</wa-timeline-item>
  <wa-timeline-item>Delivered</wa-timeline-item>
</wa-timeline>

To let a long timeline scroll sideways, wrap it in a <wa-scroller> and give the timeline a minimum width.

Sputnik 1

First artificial satellite.

Vostok 1

First human in orbit.

Apollo 11

First crewed lunar landing.

Columbia

First reusable orbiter flies.

Zarya

First ISS module.

<wa-scroller>
  <wa-timeline class="timeline-space-race" orientation="horizontal">
    <wa-timeline-item>
      <wa-icon slot="icon" name="satellite-dish"></wa-icon>
      <wa-format-date slot="opposite" date="1957-10-04" year="numeric"></wa-format-date>
      <span class="wa-heading-m">Sputnik 1</span>
      <p>First artificial satellite.</p>
    </wa-timeline-item>
    <wa-timeline-item>
      <wa-icon slot="icon" name="user-astronaut"></wa-icon>
      <wa-format-date slot="opposite" date="1961-04-12" year="numeric"></wa-format-date>
      <span class="wa-heading-m">Vostok 1</span>
      <p>First human in orbit.</p>
    </wa-timeline-item>
    <wa-timeline-item>
      <wa-icon slot="icon" name="moon"></wa-icon>
      <wa-format-date slot="opposite" date="1969-07-20" year="numeric"></wa-format-date>
      <span class="wa-heading-m">Apollo 11</span>
      <p>First crewed lunar landing.</p>
    </wa-timeline-item>
    <wa-timeline-item>
      <wa-icon slot="icon" name="shuttle-space"></wa-icon>
      <wa-format-date slot="opposite" date="1981-04-12" year="numeric"></wa-format-date>
      <span class="wa-heading-m">Columbia</span>
      <p>First reusable orbiter flies.</p>
    </wa-timeline-item>
    <wa-timeline-item>
      <wa-icon slot="icon" name="satellite"></wa-icon>
      <wa-format-date slot="opposite" date="1998-11-20" year="numeric"></wa-format-date>
      <span class="wa-heading-m">Zarya</span>
      <p>First ISS module.</p>
    </wa-timeline-item>
  </wa-timeline>
</wa-scroller>

<style>
  .timeline-space-race {
    min-inline-size: 56rem;
  }
</style>

Set the orientation attribute to auto to lay items out in a row and switch to a column when there's less than about 10em between items, so entries stay readable on small screens. Resize the example to see the switch. While laid out as a column, the timeline has the stacked custom state, so wa-timeline:state(stacked) targets it.

The default, vertical, stays a column at any width. auto measures the timeline in the browser, so a server-rendered auto timeline starts as a column and switches to a row once it hydrates.

Kickoff Beta Launch
<wa-timeline orientation="auto">
  <wa-timeline-item>
    <wa-format-date slot="opposite" date="2026-05-04T09:00:00" month="short" day="numeric"></wa-format-date>
    <span class="wa-heading-m">Kickoff</span>
  </wa-timeline-item>
  <wa-timeline-item>
    <wa-format-date slot="opposite" date="2026-06-08T09:00:00" month="short" day="numeric"></wa-format-date>
    <span class="wa-heading-m">Beta</span>
  </wa-timeline-item>
  <wa-timeline-item>
    <wa-format-date slot="opposite" date="2026-06-29T09:00:00" month="short" day="numeric"></wa-format-date>
    <span class="wa-heading-m">Launch</span>
  </wa-timeline-item>
</wa-timeline>

Don't combine auto with <wa-scroller>. Pick sideways scrolling or switching to a column, not both.

Marker Placement

Link to This Section

The marker-placement attribute sets where each marker sits relative to its item's content. The default, start, puts the marker before the content; set it to end to put the marker after the content. Marker placement only applies while the timeline is laid out as a column, including an auto timeline that has switched to one.

Draft written Edits returned Published
<wa-timeline marker-placement="end">
  <wa-timeline-item>
    <wa-format-date slot="opposite" date="2026-03-02T09:00:00" month="short" day="numeric"></wa-format-date>
    <span class="wa-heading-m">Draft written</span>
  </wa-timeline-item>
  <wa-timeline-item>
    <wa-format-date slot="opposite" date="2026-03-09T09:00:00" month="short" day="numeric"></wa-format-date>
    <span class="wa-heading-m">Edits returned</span>
  </wa-timeline-item>
  <wa-timeline-item variant="success">
    <wa-format-date slot="opposite" date="2026-03-16T09:00:00" month="short" day="numeric"></wa-format-date>
    <span class="wa-heading-m">Published</span>
  </wa-timeline-item>
</wa-timeline>

Set it to alternate to switch sides item by item, so the rail runs down the middle, which suits a wide timeline. When the timeline is narrower than 30em, it lays every item out on the start side until it has room again.

Shipped Bulk actions in the data grid

Select rows across pages and act on them all at once.

In progress Real-time collaboration

See where teammates are editing as they type.

Planned Offline mode

Keep working on a flight; sync once you land.

<wa-timeline marker-placement="alternate">
  <wa-timeline-item variant="success">
    <wa-badge slot="opposite" appearance="outlined" variant="success" pill>Shipped</wa-badge>
    <span class="wa-heading-m">Bulk actions in the data grid</span>
    <p>Select rows across pages and act on them all at once.</p>
  </wa-timeline-item>
  <wa-timeline-item variant="brand">
    <wa-badge slot="opposite" appearance="outlined" variant="brand" pill>In progress</wa-badge>
    <span class="wa-heading-m">Real-time collaboration</span>
    <p>See where teammates are editing as they type.</p>
  </wa-timeline-item>
  <wa-timeline-item>
    <wa-badge slot="opposite" appearance="outlined" pill>Planned</wa-badge>
    <span class="wa-heading-m">Offline mode</span>
    <p>Keep working on a flight; sync once you land.</p>
  </wa-timeline-item>
</wa-timeline>

Marker Alignment

Link to This Section

By default, each marker sits at the top of its item, in line with the first line of text. Set the marker-alignment attribute to center to center the marker on the item's full height instead. Marker alignment only applies while the timeline is laid out as a column, including an auto timeline that has switched to one.

Base camp

Three days of acclimatizing, card games, and weather reports.

Summit push

Left at 2 AM by headlamp. Reached the top as the sun came up.

Descent

Knees complaining, spirits high. Back to the trailhead by dusk.

<wa-timeline marker-alignment="center">
  <wa-timeline-item variant="success">
    <wa-icon slot="icon" name="campground"></wa-icon>
    <wa-card>
      <div slot="media" class="wa-frame:landscape">
        <img
          src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?auto=format&fit=crop&w=640&h=360&q=60"
          alt=""
        />
      </div>
      <span class="wa-heading-m">Base camp</span>
      <p>Three days of acclimatizing, card games, and weather reports.</p>
    </wa-card>
  </wa-timeline-item>
  <wa-timeline-item variant="success">
    <wa-icon slot="icon" name="mountain"></wa-icon>
    <wa-card>
      <div slot="media" class="wa-frame:landscape">
        <img
          src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?auto=format&fit=crop&w=640&h=360&q=60"
          alt=""
        />
      </div>
      <span class="wa-heading-m">Summit push</span>
      <p>Left at 2 AM by headlamp. Reached the top as the sun came up.</p>
    </wa-card>
  </wa-timeline-item>
  <wa-timeline-item>
    <wa-icon slot="icon" name="person-hiking"></wa-icon>
    <wa-card>
      <div slot="media" class="wa-frame:landscape">
        <img
          src="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?auto=format&fit=crop&w=640&h=360&q=60"
          alt=""
        />
      </div>
      <span class="wa-heading-m">Descent</span>
      <p>Knees complaining, spirits high. Back to the trailhead by dusk.</p>
    </wa-card>
  </wa-timeline-item>
</wa-timeline>

Providing Content

Link to This Section

An item's default slot accepts any content, so an entry can hold more than a title and a line of text.

Jamie Kim opened the pull request #2905

Adds the timeline component and its docs.

View Changes
Riley Park requested changes Changes requested

Can we add a test for an empty opposite slot before merging this?

Jamie Kim pushed 2 commits
  • a1f3c9e Test the empty opposite slot
  • 7b2d410 Tidy the docs examples
Riley Park approved these changes Approved

Looks great. The new tests are a nice touch.

Merged into next
<wa-timeline class="timeline-activity">
  <wa-timeline-item>
    <wa-avatar slot="icon" initials="JK" label="Jamie Kim"></wa-avatar>
    <wa-format-date
      slot="opposite"
      date="2026-09-14T09:12:00"
      month="short"
      day="numeric"
      hour="numeric"
      minute="numeric"
    ></wa-format-date>
    <div class="wa-stack wa-gap-xs">
      <div class="wa-cluster wa-gap-2xs">
        <span class="wa-heading-m">Jamie Kim</span>
        opened the pull request
        <wa-badge appearance="outlined" pill>#2905</wa-badge>
      </div>
      <p>Adds the timeline component and its docs.</p>
      <div class="wa-cluster">
        <wa-button size="s" appearance="outlined">View Changes</wa-button>
      </div>
    </div>
  </wa-timeline-item>
  <wa-timeline-item>
    <wa-avatar slot="icon" initials="RP" label="Riley Park"></wa-avatar>
    <wa-format-date
      slot="opposite"
      date="2026-09-14T11:03:00"
      month="short"
      day="numeric"
      hour="numeric"
      minute="numeric"
    ></wa-format-date>
    <div class="wa-stack wa-gap-xs">
      <div class="wa-cluster wa-gap-2xs">
        <span class="wa-heading-m">Riley Park</span>
        requested changes
        <wa-badge variant="warning" appearance="outlined" pill>Changes requested</wa-badge>
      </div>
      <p>Can we add a test for an empty <code>opposite</code> slot before merging this?</p>
    </div>
  </wa-timeline-item>
  <wa-timeline-item>
    <wa-avatar slot="icon" initials="JK" label="Jamie Kim"></wa-avatar>
    <wa-format-date
      slot="opposite"
      date="2026-09-15T08:20:00"
      month="short"
      day="numeric"
      hour="numeric"
      minute="numeric"
    ></wa-format-date>
    <div class="wa-stack wa-gap-xs">
      <div class="wa-cluster wa-gap-2xs">
        <span class="wa-heading-m">Jamie Kim</span>
        pushed 2 commits
      </div>
      <ul class="wa-body-s">
        <li><code>a1f3c9e</code> Test the empty opposite slot</li>
        <li><code>7b2d410</code> Tidy the docs examples</li>
      </ul>
    </div>
  </wa-timeline-item>
  <wa-timeline-item>
    <wa-avatar slot="icon" initials="RP" label="Riley Park"></wa-avatar>
    <wa-format-date
      slot="opposite"
      date="2026-09-15T08:47:00"
      month="short"
      day="numeric"
      hour="numeric"
      minute="numeric"
    ></wa-format-date>
    <div class="wa-stack wa-gap-xs">
      <div class="wa-cluster wa-gap-2xs">
        <span class="wa-heading-m">Riley Park</span>
        approved these changes
        <wa-badge variant="success" appearance="outlined" pill>Approved</wa-badge>
      </div>
      <p>Looks great. The new tests are a nice touch.</p>
    </div>
  </wa-timeline-item>
  <wa-timeline-item variant="brand">
    <wa-icon slot="icon" name="code-merge"></wa-icon>
    <wa-format-date
      slot="opposite"
      date="2026-09-15T09:02:00"
      month="short"
      day="numeric"
      hour="numeric"
      minute="numeric"
    ></wa-format-date>
    <div class="wa-cluster wa-gap-2xs">
      <span class="wa-heading-m">Merged</span>
      into <code>next</code>
    </div>
  </wa-timeline-item>
</wa-timeline>

<style>
  .timeline-activity {
    --icon-marker-size: 2.5em;
  }

  .timeline-activity ul {
    margin: 0;
    padding-inline-start: 1.25em;
  }
</style>

Grouping Entries

Link to This Section

To group entries under headings, such as by day, give each group its own heading and its own timeline. Keep the headings outside the timelines, since a timeline should only hold items. Set the label attribute on each timeline so screen reader users can tell the groups apart.

Today

Payment received

Paid in full by bank transfer.

Reminder sent

A second notice went to the billing contact.

Yesterday

Invoice sent

Due in 30 days.

Quote approved

The client signed off on the estimate.

<div class="wa-stack">
  <h4>Today</h4>
  <wa-timeline label="Today">
    <wa-timeline-item variant="success">
      <span class="wa-heading-m">Payment received</span>
      <p>Paid in full by bank transfer.</p>
    </wa-timeline-item>
    <wa-timeline-item>
      <span class="wa-heading-m">Reminder sent</span>
      <p>A second notice went to the billing contact.</p>
    </wa-timeline-item>
  </wa-timeline>

  <h4>Yesterday</h4>
  <wa-timeline label="Yesterday">
    <wa-timeline-item>
      <span class="wa-heading-m">Invoice sent</span>
      <p>Due in 30 days.</p>
    </wa-timeline-item>
    <wa-timeline-item>
      <span class="wa-heading-m">Quote approved</span>
      <p>The client signed off on the estimate.</p>
    </wa-timeline-item>
  </wa-timeline>
</div>

Adding Entries

Link to This Section

Append a <wa-timeline-item> to add an entry at the end. To show the newest entry at the top, put it first in the markup and add entries with prepend(). Reading and focus order follow document order, so they match the screen.

1–0 Goal, Rovers

A low cross from the left, tapped in at the far post.

0–0 Kickoff

Rovers get us under way, playing left to right.

Add Play
<div class="wa-stack">
  <wa-timeline id="timeline-newest">
    <wa-timeline-item variant="success">
      <wa-badge slot="opposite" appearance="outlined" pill>1–0</wa-badge>
      <span class="wa-heading-m">Goal, Rovers</span>
      <p>A low cross from the left, tapped in at the far post.</p>
    </wa-timeline-item>
    <wa-timeline-item>
      <wa-badge slot="opposite" appearance="outlined" pill>0–0</wa-badge>
      <span class="wa-heading-m">Kickoff</span>
      <p>Rovers get us under way, playing left to right.</p>
    </wa-timeline-item>
  </wa-timeline>

  <wa-divider></wa-divider>

  <wa-button id="timeline-newest-advance" appearance="filled">Add Play</wa-button>
</div>

<script>
  const timelineNewest = document.getElementById('timeline-newest');
  const timelineNewestButton = document.getElementById('timeline-newest-advance');
  const timelineNewestPlays = [
    {
      score: '1–0',
      variant: 'warning',
      label: 'Yellow card',
      body: 'A late tackle in midfield. The referee has a word.',
    },
    {
      score: '1–1',
      variant: 'brand',
      label: 'Goal, City',
      body: 'A free kick curled over the wall and into the corner.',
    },
    { score: '1–1', variant: 'neutral', label: 'Full time', body: 'Honors even. Both sides will take the point.' },
  ];

  timelineNewestButton.addEventListener('click', () => {
    const next = timelineNewestPlays.shift();
    if (!next) return;

    const item = document.createElement('wa-timeline-item');
    item.variant = next.variant;
    item.innerHTML = `<wa-badge slot="opposite" appearance="outlined" pill>${next.score}</wa-badge><span class="wa-heading-m">${next.label}</span><p>${next.body}</p>`;
    timelineNewest.prepend(item);

    if (timelineNewestPlays.length === 0) timelineNewestButton.disabled = true;
  });
</script>

With marker-placement="alternate", use append instead of prepend.
Sides are assigned in document order, so prepending an entry moves existing entries to the other side.

Customizing

Link to This Section

Use the exported CSS parts and custom properties to restyle the timeline. Most parts, such as marker and connector, belong to <wa-timeline-item>, so the selector targets the items, not the timeline; see the Timeline Item page for every part an item exposes. Each item can also set the --marker-size, --icon-marker-size, and --connector-gap custom properties for itself.

This example sets the timeline's --gap, --marker-size, and --connector-width custom properties, and the first entry sets a larger --marker-size for itself.

Adopted

Eight weeks old and already in charge.

First vet visit

A clean bill of health.

Learned the word "dinner"

Responds to it from three rooms away.

Claimed the window sill

The sunny end is hers now. Negotiations are closed.

Turned one

Celebrated with a new basket and two friends.

<wa-timeline class="timeline-mittens" marker-placement="alternate">
  <wa-timeline-item style="--marker-size: 1.5em;">
    <wa-format-date slot="opposite" date="2025-06-14" month="long" year="numeric"></wa-format-date>
    <div class="wa-flank:end wa-gap-s">
      <div>
        <span class="wa-heading-m">Adopted</span>
        <p>Eight weeks old and already in charge.</p>
      </div>
      <div class="wa-frame wa-border-radius-m">
        <img
          src="https://images.unsplash.com/photo-1547191783-94d5f8f6d8b1?auto=format&fit=crop&w=160&h=160&q=60"
          alt=""
        />
      </div>
    </div>
  </wa-timeline-item>
  <wa-timeline-item>
    <wa-format-date slot="opposite" date="2025-07-02" month="long" year="numeric"></wa-format-date>
    <div class="wa-flank wa-gap-s">
      <div class="wa-frame wa-border-radius-m">
        <img
          src="https://images.unsplash.com/photo-1529778873920-4da4926a72c2?auto=format&fit=crop&w=160&h=160&q=60"
          alt=""
        />
      </div>
      <div>
        <span class="wa-heading-m">First vet visit</span>
        <p>A clean bill of health.</p>
      </div>
    </div>
  </wa-timeline-item>
  <wa-timeline-item>
    <wa-format-date slot="opposite" date="2025-09-08" month="long" year="numeric"></wa-format-date>
    <div class="wa-flank:end wa-gap-s">
      <div>
        <span class="wa-heading-m">Learned the word "dinner"</span>
        <p>Responds to it from three rooms away.</p>
      </div>
      <div class="wa-frame wa-border-radius-m">
        <img
          src="https://images.unsplash.com/photo-1591871937573-74dbba515c4c?auto=format&fit=crop&w=160&h=160&q=60"
          alt=""
        />
      </div>
    </div>
  </wa-timeline-item>
  <wa-timeline-item>
    <wa-format-date slot="opposite" date="2025-11-19" month="long" year="numeric"></wa-format-date>
    <div class="wa-flank wa-gap-s">
      <div class="wa-frame wa-border-radius-m">
        <img
          src="https://images.unsplash.com/photo-1559209172-0ff8f6d49ff7?auto=format&fit=crop&w=160&h=160&q=60"
          alt=""
        />
      </div>
      <div>
        <span class="wa-heading-m">Claimed the window sill</span>
        <p>The sunny end is hers now. Negotiations are closed.</p>
      </div>
    </div>
  </wa-timeline-item>
  <wa-timeline-item>
    <wa-format-date slot="opposite" date="2026-06-14" month="long" year="numeric"></wa-format-date>
    <div class="wa-flank:end wa-gap-s">
      <div>
        <span class="wa-heading-m">Turned one</span>
        <p>Celebrated with a new basket and two friends.</p>
      </div>
      <div class="wa-frame wa-border-radius-m">
        <img
          src="https://images.unsplash.com/photo-1517331156700-3c241d2b4d83?auto=format&fit=crop&w=160&h=160&q=60"
          alt=""
        />
      </div>
    </div>
  </wa-timeline-item>
</wa-timeline>

<style>
  .timeline-mittens {
    --gap: var(--wa-space-2xl);
    --marker-size: 0.75em;
    --connector-width: 0.15em;
  }

  .timeline-mittens .wa-frame {
    inline-size: 4rem;
    flex: none;
  }
</style>

Here the connector and markers become one rule with diamond stops: the --connector-gap custom property is set to 0px so the line runs straight into each marker, and the marker part is rotated into a diamond. The latest release takes the brand variant so it stands out, and version numbers sit in the opposite slot as <wa-badge>s.

v3.14 Added the stepper component

Guides users through a process one step at a time.

v3.15 Added the lightbox component

Shows images and videos in a full-screen viewer that opens from their thumbnails.

v3.16 Added the timeline component

Lays out a chronological list of events, like this one.

<wa-timeline class="release-timeline">
  <wa-timeline-item>
    <wa-badge slot="opposite" appearance="outlined" pill>v3.14</wa-badge>
    <span class="wa-heading-m">Added the stepper component</span>
    <p>Guides users through a process one step at a time.</p>
  </wa-timeline-item>
  <wa-timeline-item>
    <wa-badge slot="opposite" appearance="outlined" pill>v3.15</wa-badge>
    <span class="wa-heading-m">Added the lightbox component</span>
    <p>Shows images and videos in a full-screen viewer that opens from their thumbnails.</p>
  </wa-timeline-item>
  <wa-timeline-item variant="brand">
    <wa-badge slot="opposite" appearance="outlined" variant="brand" pill>v3.16</wa-badge>
    <span class="wa-heading-m">Added the timeline component</span>
    <p>Lays out a chronological list of events, like this one.</p>
  </wa-timeline-item>
</wa-timeline>

<style>
  .release-timeline {
    --marker-size: 0.875em;
    --connector-gap: 0px;
    --connector-color: var(--wa-color-neutral-fill-quiet);
  }

  .release-timeline wa-timeline-item::part(marker) {
    rotate: 45deg;
    border-radius: var(--wa-border-radius-s);
    background-color: var(--wa-color-neutral-fill-loud);
  }

  .release-timeline wa-timeline-item[variant='brand']::part(marker) {
    background-color: var(--wa-color-brand-fill-loud);
  }
</style>

Accessibility Considerations

Link to This Section
  • Structure. The timeline renders an ordered list, and each <wa-timeline-item> carries role="listitem". Set the label attribute whenever more than one timeline appears on the same page, so screen reader users can tell them apart.
  • Keyboard. Nothing in the timeline takes focus. Items are records, not controls, so the timeline never intercepts clicks or adds keyboard handling. If an entry needs to link somewhere or trigger an action, put a real <a> or <wa-button> in its content.
  • Added entries aren't announced. Adding a <wa-timeline-item> updates the list silently; there's no live region. If an update needs to be announced, do it from your own live region rather than relying on the timeline.
  • Color and meaning. The variant attribute is cosmetic. It changes color, which doesn't carry meaning on its own, so state the reason in the item's visible content rather than relying on color alone.
  • Custom icons. When the icon slot holds an icon that's the only indicator of an item's meaning (e.g. a checkmark for "completed" with no other label), give it an accessible name with <wa-icon label="...">. A marker that only repeats what the item's own content already says can stay decorative.

API

Link to This Section

Importing

Link to This Section

If you're using the autoloader or a hosted project, components load on demand — no manual import needed. To cherry-pick a component manually, use one of the following snippets.

CDN npm Self-Hosted React

Import this component directly from the CDN:

import 'https://ka-f.webawesome.com/[email protected]/components/timeline/timeline.js';

After installing Web Awesome via npm, import this component:

import '@awesome.me/webawesome/dist/components/timeline/timeline.js';

If you're self-hosting Web Awesome, import this component from your server:

import './webawesome/dist/components/timeline/timeline.js';

To import this component for React 18 or below, use the following code:

import WaTimeline from '@awesome.me/webawesome/dist/react/timeline/index.js';

Slots

Link to This Section

Learn more about using slots.

Name Description
(default) One or more <wa-timeline-item> elements.

Attributes & Properties

Link to This Section

Learn more about attributes and properties.

Name Description Reflects
label
label
A label that describes the timeline to assistive devices. Especially useful when more than one is on the page.
Type string
Default ''
markerAlignment
marker-alignment
Where the marker sits along its item. start lines it up with the first line of text. center centers it on the item's full height and runs the connector behind it as one line, which suits cards. Only applies while the timeline is laid out as a column.
Type 'start' | 'center'
Default 'start'
markerPlacement
marker-placement
Which side of each item's content the marker sits on. start puts the marker before the content and end puts it after. alternate switches sides on every other item, so the rail runs down the middle. An alternating timeline narrower than 30em lays every item out like start until it has room. Only applies while the timeline is laid out as a column.
Type 'start' | 'end' | 'alternate'
Default 'start'
orientation
orientation
The timeline's layout direction. auto lays the items out in a row when there's room and in a column when the timeline is too narrow. It measures in the browser, so a server-rendered auto timeline starts as a column. vertical stays the default.
Type 'horizontal' | 'vertical' | 'auto'
Default 'vertical'

CSS Custom Properties

Link to This Section

Learn more about CSS custom properties.

Name Description
--connector-color
The color of the connector line.
Default var(--wa-color-neutral-fill-normal)
--connector-gap
The gap between a marker's edge and the connector line. Use a length such as 0px, not a bare 0, to remove it.
Default 0.35em
--connector-width
The thickness of the connector line, in either orientation.
Default var(--wa-border-width-m)
--gap
The space between items. Connectors are sized from this value, so set it here instead of setting gap on the timeline part. Use a length such as 0px, not a bare 0, to remove it.
Default var(--wa-space-l)
--icon-marker-size
The size of a marker whose item has content in its icon slot, such as an icon or avatar. Usually set here so every item matches.
Default 2em
--marker-size
The size of a marker with no icon. Usually set here so every item matches.
Default 1em

Custom States

Link to This Section

Learn more about custom states.

Name Description CSS selector
stacked Applied while the items are laid out in a column, whether by orientation="vertical" or because an auto timeline is too narrow for a row. :state(stacked)

CSS Parts

Link to This Section

Learn more about CSS parts.

Name Description CSS selector
timeline The ordered list that lays out the items. ::part(timeline)

Dependencies

Link to This Section

This component automatically imports the following elements. Sub-dependencies, if any exist, will also be included in this list.

  • <wa-timeline-item>

SSR

Link to This Section

Learn more about Server-Side Rendering (SSR).

During SSR, <wa-timeline> can't reach its items, so each item renders with the default start placement and start alignment until it hydrates. The list itself follows orientation and marker-placement right away, so a horizontal or alternating timeline doesn't lay out correctly until then. A server-rendered alternating timeline also starts out alternating and only stacks after it hydrates, if it's too narrow. A server-rendered auto timeline is a column until it hydrates and measures its width.

Need a hand? Report a bug Ask for help
Go Make Something Awesome
Version 3.15.0 © Fonticons, Inc.
  • Terms
  • Privacy
  • Refunds
  • Core License
  • Pro License

Quick Links

  • Components
  • CSS Utilities
  • Theming
  • Using with AI
  • Changelog
  • Help & Support

Recent Searches

    D'oh! No results for “”

    Suggest on GitHub Ask on Discord
    Navigate Select
    Close Esc

    We Have Cookies…

    We use cookies to make webawesome.com work better by storing limited information about your usage.

    We value your privacy, so we won't use them for evil or ask you to join the dark side.

    Customize
    Necessary Only Accept All
    Strictly Necessary
    Required to make the site function correctly — cannot be turned off
    Functionality Analytics
    Cancel Confirm Cookie Choices