Timeline

Components/Lists/Timeline

Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/timeline

Overview

Copy

Timeline displays a vertical list of past events in a chronological order.

Do

  • Use it to log and illustrate a history of events (newest on top, oldest at the bottom).
  • Use it when the list of events is actionable (e.g., user can view event's documents).

Don't

  • Don't use it to demonstrate the progress of server states or to show task SLA status. Use <HorizontalTimeline/> instead.
  • Don't use it as part of an onboarding flow. Use <Stepper/> component instead.

Feature examples

Structure

Add content to a timeline by using `items` prop. Each item has props to control these containers:
 - `customPrefix` - overrides the default circle with a specified icon to mark important milestones.
 - `label` - describes the event.
 - `labelAction` - enables an action that provides more info or leads to an event.
 - `suffix` - displays event's date or other additional info.

Note that all of these containers are nodes (i.e., can store any component as a child item). Their positions are fixed.

Copy

Gap

Control vertical distance between the items with a `gap` prop.

Default value is 30 px.

Copy

Label

Set the content for an item's label with a `label` prop.

Label describes the event of the Timeline item. It wraps into multiple lines where necessary.

Note that the label container accepts any component as a child item.

Copy

Label action

Add an action button for a Timeline's item using a `labelAction` prop.

Use it as a link to actions or further information about the Timeline item.

Copy

Custom Prefix

Set a custom icon for a Timeline item with a `customPrefix` prop. Use it to highlight important milestones or errors.

Control it for each item individually.

When not defined, prefix is a default filled-in circle.

Copy

Suffix

Add more information to the Timeline item with a `suffix` prop.

Use it to show the date of an event (but it can also render any component as a child item).

Copy

Common use case examples

Store Order Activity

Illustrate the history of a product order with a Timeline, stored inside a <Card/>.

In this case, users can fill in recent events into the Timeline themselves, change events' status, and view more related information.

Copy

Code

Copy

Props

NameTypeDefaultDescription
dataHookstring—Applies a data-hook HTML attribute to be used in the tests.
gapstring—Sets the distance that separates each item from the one below.
items (required)TimelineItem[]—Defines each individual event item in the component: - label stores a text string naming the event or renders other components as its children - labelAction stores an action button (or other components) related to the event - customPrefix defines a custom milestone symbol for an item on the vertical axis - suffix stores a date of the event (or other components)
skin"standard" | "neutral" | "dark"—Sets the skin of the component.

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
getLabelTextGets the label text of timeline item by index
getSuffixTextGet the suffix text of timeline item by index
getSkinGets skin type
existsChecks whether the component found with the given data hook.
elementGets the component root element.
clickClicks on the component root element.
baseReturns UniDriver for the base element.

Changelog

  • 1.344.0 (2026-10-28) — maintenance release, no component-specific changes
  • 1.340.0 (2026-10-21) — maintenance release, no component-specific changes
  • 1.339.0 (2026-10-19) — maintenance release, no component-specific changes
  • 1.338.0 (2026-10-15) — maintenance release, no component-specific changes
  • 1.331.0 (2026-10-01) — maintenance release, no component-specific changes
  • 1.329.0 (2026-09-24) — maintenance release, no component-specific changes
  • 1.325.0 (2026-09-17) — maintenance release, no component-specific changes
  • 1.310.0 (2026-08-10) — maintenance release, no component-specific changes
  • 1.292.0 (2026-06-22) — maintenance release, no component-specific changes
  • 1.291.0 (2026-06-19) — maintenance release, no component-specific changes
  • 1.266.0 (2026-04-07) — maintenance release, no component-specific changes
  • 1.260.0 (2026-03-17) — maintenance release, no component-specific changes
  • 1.258.0 (2026-02-23) — breaking: tokenization (#15948)
  • 1.254.0 (2026-02-03) — maintenance release, no component-specific changes
  • 1.154.0 (2025-01-16) — feat: add skin and line properties, support medium size icons as prefix (#14436)
  • 1.148.0 (2024-12-16) — maintenance release, no component-specific changes
  • 1.138.1 (2024-10-30) — maintenance release, no component-specific changes
  • 1.102.0 (2024-04-16) — maintenance release, no component-specific changes
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 30 October 2026

Did this help?