Skip to main content

Timeline

Displays a list of content in chronological order.

github
View source code
figma
View design

Migration Information

For teams migrating from the V1 to V2 component, please refer to the migration guide for changes to the component.
Component Guide
import { Timeline } from '@uhg-abyss/web/ui/Timeline';
      () => {
        return (
          <Timeline type="card" activeStep={1}>
            <Timeline.Step
              title="Lorem ipsum"
              description="Lorem ipsum dolor sit amet consectetur adipiscing."
              date={dayjs('2025-05-30').format('MM/DD/YYYY')}
            />
            <Timeline.Step
              title="Lorem ipsum"
              description="Lorem ipsum dolor sit amet consectetur adipiscing."
              date={dayjs('2025-05-31').format('MM/DD/YYYY')}
            />
            <Timeline.Step
              title="Lorem ipsum"
              description="Lorem ipsum dolor sit amet consectetur adipiscing."
              date={dayjs('2025-06-01').format('MM/DD/YYYY')}
            />
            <Timeline.Step
              title="Lorem ipsum"
              description="Lorem ipsum dolor sit amet consectetur adipiscing."
              date={dayjs('2025-06-02').format('MM/DD/YYYY')}
            />
          </Timeline>
        );
      };

      Steps​

      Use the Timeline.Step subcomponent to define each step in the Timeline. The steps are rendered in the same order they are defined, so the first child will be the first step, the second child will be the second step, and so on.

      This section covers the props available for Timeline.Step.

      Title​

      Use the title prop to set the title of the step. This prop is required.

      Date​

      Use the date prop to set the date of the step. This prop accepts a string or an object with a startDate and endDate. The examples on this page use Day.js to format the dates, but teams are free to use any library they wish.

      Hide completion state​

      Use the hideCompletionState prop to hide the completion state below the title. Note that the state will still be read by screen readers for accessibility purposes.

      Status​

      Use the status prop to set the status of the step. The available statuses are 'neutral', 'info', warning', and 'error'. The default value is 'neutral'.

      Note

      Only the active step will change appearance based on the status. Additionally, if type is set to 'card', the card will change appearance based on the status of the active step.

      It is recommended to include ariaText when using the status prop to ensure that the status is accessible to screen reader users, particularly when not using the 'neutral' status. The value of this prop will be set as the title for the status icon.

      Description​

      Use the description prop to add a short description for the step. More information can be provided in the detail card when using the 'card' type Timeline.

      Button​

      Use the button prop to add a button to the step. The button prop accepts an object of type ButtonProps, which accepts most props of the Button component, with the exception of size and variant, which are set by the Timeline and cannot be altered.

      Helper​

      Use the helper prop to display a help icon next to the label. Simply passing a string value will render the default helper, a Tooltip containing that string. The helper can be customized by passing in a node. It is recommended to use either a Tooltip or a Popover. See When should I use a Tooltip vs. a Popover? for more information on best practices regarding the two.

      Title​

      Use the title prop to set the title of the Timeline. The default is "Timeline history". By default, the title is rendered as an <h3>, but this can be configured using the headingLevel prop.

      Active step​

      Use the activeStep prop to set the currently active step in the Timeline. This prop accepts the 1-indexed step number (i.e. 1 is the first step, not 0).

      Note

      If the value of activeStep is higher than the number of steps, the Timeline will display all steps as complete without any using the active step styling.

      Active step completion state​

      By default, the activeStep will be in progress. Use the activeStepCompletionState prop to change the completion state of the active step. The available states are 'in-progress' and 'completed'. The default value it 'in-progress'.

      Tip

      Use 'completed' to indicate that the current step in the process is complete, but the next step hasn't yet begun

      Hide step numbers​

      Use the hideStepNumbers prop to hide the step numbers in the Timeline steps and in the active step card. Note that the step numbers will still be read by screen readers for accessibility purposes.

      Type​

      Use the type prop to change the appearance of the Timeline. The 'card' type displays the Timeline in a card and includes a detail card to display more information about the current step. The 'simple' type displays the Timeline without any container or detail card. The default value is 'card'.

      Extra content​

      Use the extraContent prop to add custom content below the Timeline.

      Card config​

      The cardConfig prop allows you to customize the detail card for the 'card' type Timeline. It accepts an object of the following type:

      {
        ariaText?: string;
        headingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
        helper?: ReactNode | string;
        description?: string;
        extraContent?: ReactNode;
        buttons?: {
          filledButton: ButtonProps;
          outlineButton?: ButtonProps;
        };
      }

      The ariaText prop adds additional text for screen readers to be read before the card title.

      The headingLevel prop sets the heading level of the card title, which is an <h2> by default.

      The helper prop displays an info icon next to the title. See Helper above for more information on how to use it.

      The description prop adds a longer description of the current step.

      The extraContent prop allows you to add additional JSX content to the detail card.

      The buttons prop allows you to add buttons to the detail card. ButtonProps is an object that accepts most props of the Button component, with the exception of size and variant, which are set by the Timeline and cannot be altered. When using buttons, the filledButton is always required, but the outlineButton is optional.

      Reverse order​

      By default, the steps are rendered in the order they are defined, with the first step at the top and the last step at the bottom. Use the reverseOrder prop to reverse this order, so that the last step is at the top and the first step is at the bottom.

      Comparison to StepTracker​

      Timeline and StepTracker are similar components, but should not be used interchangeably. Both components display a history of completed steps in, the current progress of, and information about the remaining steps in a process. What differentiates one from the other is whether the information displayed is based on immediate user engagement with the user interface or not.

      Timeline​

      The Timeline component is used to inform users of the status of a process with no immediate user input. An example is a claims submission status page where the user can see the progress of their claim through the various stages, but cannot interact with the steps directly.

      StepTracker​

      The StepTracker is used to guide people through a number of steps to complete in a process. The user navigates through the steps with other components in the UI, typically buttons. An example is a multi-step form where the user fills out information in each step and can navigate back and forth between steps.

      Timeline Props​

      Name
      Type
      		DefaultRequiredA11yDescription
      activeStep
      number
      The 1-indexed active step number
      activeStepCompletionState
      "completed" | "in-progress" | undefined
      'in-progress'
      The completion state of the active step
      cardConfig
      Pick<ActiveStepCardProps, "headingLevel" | "description" | "ariaText" | "buttons" | "helper" | "extraContent"> | undefined
      Configuration for the active step card
      Configuration for the Timeline card
      children
      string | number | bigint | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | Promise<...> | null | undefined
      The steps to display in the Timeline
      className
      string | undefined
      CSS class name to apply to each element within the component
      css
      CSSProperties | Partial<Record<"abyss-timeline-header" | "abyss-timeline-heading" | "abyss-timeline-root" | "abyss-timeline-step-count" | "abyss-timeline-step-container" | ... 14 more ... | "abyss-timeline-active-step-card-tooltip-icon", CSSProperties>> | undefined
      Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation
      See CSS Prop Styling for more information
      data-testid
      string | undefined
      Suffix used to create a unique ID used for automated testing
      See Component Testing for more information
      disableDefaultProviderProps
      boolean | undefined
      false
      If set to true, the component will not use the DefaultPropsProvider values.

      If you aren’t using the DefaultPropsProvider, this prop can be ignored.
      extraContent
      string | number | bigint | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | Promise<...> | null | undefined
      Extra content to display below the Timeline
      headingLevel
      1 | 2 | 3 | 4 | 5 | 6 | undefined
      3
      The semantic heading level for the Timeline's title, so it fits correctly into the page's heading structure for screen readers.
      hiddenFrom
      Breakpoint | undefined
      When defined, the component is hidden once the screen width reaches the specified breakpoint.
      hideStepNumbers
      boolean | undefined
      false
      If true, the Timeline step numbers will be hidden
      reverseOrder
      boolean | undefined
      false
      If true, the steps will be displayed in reverse order (last step first)
      slotProps
      Partial<Record<string, SlotPropsValue<string>>> | undefined
      Props to pass to individual internal slots of the component, keyed by the slot name
      (e.g. 'button-root'). Supports className, css, style, aria-*, data-*,
      data-testid, and nested slotProps for child Abyss components.
      See slotProps for more information
      title
      string | undefined
      'Timeline history'
      The Timeline's heading text, used as the accessible name for the Timeline region via aria-labelledby.
      type
      "card" | "simple" | undefined
      'card'
      The Timeline type
      visibleFrom
      Breakpoint | undefined
      When defined, the component is hidden until the screen width reaches the specified breakpoint.

      Timeline.Step Props​

      Name
      Type
      		DefaultRequiredA11yDescription
      active
      boolean
      false
      If true, this step is the active step
      ariaText
      string | undefined
      If present, this value will be added as hidden text on the step status icon for screen readers
      button
      TimelineStepButton | undefined
      If present, the step will display a button
      className
      string | undefined
      CSS class name to apply to each element within the component
      completionState
      "completed" | "in-progress" | "not-completed"
      'not-completed'
      The step's completion state
      css
      CSSProperties | Partial<Record<"abyss-timeline-step-text" | "abyss-timeline-step-button" | "abyss-timeline-step-header" | "abyss-timeline-step-track" | "abyss-timeline-step-heading" | ... 12 more ... | "abyss-timeline-step-timestamp-separator", CSSProperties>> | undefined
      Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation
      See CSS Prop Styling for more information
      data-testid
      string | undefined
      Suffix used to create a unique ID used for automated testing
      See Component Testing for more information
      date
      string | { startDate: string; endDate: string; } | undefined
      The step's date
      description
      string | undefined
      The step's description
      disableDefaultProviderProps
      boolean | undefined
      false
      If set to true, the component will not use the DefaultPropsProvider values.

      If you aren’t using the DefaultPropsProvider, this prop can be ignored.
      helper
      string | number | bigint | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | Promise<...> | null | undefined
      Helper element next to step title
      hiddenFrom
      Breakpoint | undefined
      When defined, the component is hidden once the screen width reaches the specified breakpoint.
      hideCompletionState
      boolean | undefined
      false
      If true, the step completion state will not be displayed
      hideStepNumber
      boolean | undefined
      false
      If true, the step number will be hidden
      isLastStep
      boolean
      false
      If true, this step is the last step in the timeline
      precedesActiveStep
      boolean | undefined
      false
      If true, this step immediately precedes the active step in chronological order.
      Only relevant when reverseOrder is true, where this step is rendered directly
      before the active step in display order.
      reverseOrder
      boolean | undefined
      false
      If true, the steps will be displayed in reverse order (last step first)
      slotProps
      Partial<Record<string, SlotPropsValue<string>>> | undefined
      Props to pass to individual internal slots of the component, keyed by the slot name
      (e.g. 'button-root'). Supports className, css, style, aria-*, data-*,
      data-testid, and nested slotProps for child Abyss components.
      See slotProps for more information
      status
      "error" | "info" | "warning" | "neutral" | undefined
      'neutral'
      The step's status
      stepNumber
      number
      The step's number
      title
      string
      The step's title
      visibleFrom
      Breakpoint | undefined
      When defined, the component is hidden until the screen width reaches the specified breakpoint.

      Timeline Classes​

      Class NameDescription
      .abyss-timeline-active-step-card-button-containerTimeline active step card button container
      .abyss-timeline-active-step-card-contentTimeline active step card content container
      .abyss-timeline-active-step-card-descriptionTimeline active step card description text element
      .abyss-timeline-active-step-card-extra-content-containerTimeline active step card extra content container
      .abyss-timeline-active-step-card-eyebrowTimeline active step card eyebrow text element
      .abyss-timeline-active-step-card-headerTimeline active step card header section
      .abyss-timeline-active-step-card-header-textTimeline active step card header text container
      .abyss-timeline-active-step-card-headingTimeline active step card heading text element
      .abyss-timeline-active-step-card-primary-buttonTimeline active step card primary button
      .abyss-timeline-active-step-card-rootTimeline active step card root element
      .abyss-timeline-active-step-card-secondary-buttonTimeline active step card secondary button
      .abyss-timeline-active-step-card-tooltipTimeline active step card tooltip element
      .abyss-timeline-active-step-card-tooltip-iconTimeline active step card tooltip icon element
      .abyss-timeline-card-rootTimeline card root element
      .abyss-timeline-extra-content-containerTimeline active step card extra content container
      .abyss-timeline-headerTimeline header element
      .abyss-timeline-headingTimeline heading element
      .abyss-timeline-rootTimeline root element
      .abyss-timeline-step-containerTimeline step container element
      .abyss-timeline-step-countTimeline step count element

      Timeline.Step Classes​

      Class NameDescription
      .abyss-timeline-step-buttonTimeline step button element
      .abyss-timeline-step-completed-track-lineTimeline step completed track line element
      .abyss-timeline-step-contentTimeline step content container
      .abyss-timeline-step-descriptionTimeline step description element
      .abyss-timeline-step-headerTimeline step header element
      .abyss-timeline-step-headingTimeline step heading element
      .abyss-timeline-step-not-complete-status-indicatorTimeline step not complete status indicator element
      .abyss-timeline-step-not-completed-track-lineTimeline step not completed track line element
      .abyss-timeline-step-rootTimeline step root element
      .abyss-timeline-step-status-indicatorTimeline step status indicator element
      .abyss-timeline-step-status-indicator-iconTimeline step status indicator icon element
      .abyss-timeline-step-textTimeline step text container
      .abyss-timeline-step-timestampTimeline step timestamp element
      .abyss-timeline-step-timestamp-separatorTimeline step timestamp separator element
      .abyss-timeline-step-tooltipTimeline step tooltip element
      .abyss-timeline-step-tooltip-iconTimeline step tooltip icon element
      .abyss-timeline-step-trackTimeline step track element
      .abyss-timeline-step-trackerTimeline step tracker element

      Component Tokens​

      Tip

      Click on the token row to copy the token to your clipboard.

      Timeline Tokens​

      Token NameValue
      timeline.color.border.active-step-card.container.error
      #990000
      timeline.color.border.active-step-card.container.neutral
      #002677
      timeline.color.border.active-step-card.container.info
      #126ECF
      timeline.color.border.active-step-card.container.warning
      #C24E14
      timeline.color.border.card.container
      #CBCCCD
      timeline.color.border.step.status-indicator.not-completed
      #4B4D4F
      timeline.color.border.step.track.not-completed
      #4B4D4F
      timeline.color.icon.info-icon.active
      #002677
      timeline.color.icon.info-icon.hover
      #004BA0
      timeline.color.icon.info-icon.rest
      #196ECF
      timeline.color.icon.step.status-indicator.error
      #FFFFFF
      timeline.color.icon.step.status-indicator.info
      #FFFFFF
      timeline.color.icon.step.status-indicator.neutral.active
      #FFFFFF
      timeline.color.icon.step.status-indicator.neutral.inactive
      #002677
      timeline.color.icon.step.status-indicator.warning
      #FFFFFF
      timeline.color.surface.active-step-card.container.error
      #FCF0F0
      timeline.color.surface.active-step-card.container.info
      #EEF4FF
      timeline.color.surface.active-step-card.container.neutral
      #EEF4FF
      timeline.color.surface.active-step-card.container.warning
      #FFFBEB
      timeline.color.surface.card.container
      #FFFFFF
      timeline.color.surface.step.status-indicator.error
      #990000
      timeline.color.surface.step.status-indicator.info
      #196ECF
      timeline.color.surface.step.status-indicator.neutral
      #002677
      timeline.color.surface.step.status-indicator.warning
      #C24E14
      timeline.color.surface.step.track.completed.error
      #990000
      timeline.color.surface.step.track.completed.info
      #196ECF
      timeline.color.surface.step.track.completed.neutral
      #002677
      timeline.color.surface.step.track.completed.warning
      #C24E14
      timeline.color.text.active-step-card.paragraph
      #4B4D4F
      timeline.color.text.active-step-card.eyebrow.error
      #990000
      timeline.color.text.active-step-card.eyebrow.info
      #126ECF
      timeline.color.text.active-step-card.eyebrow.neutral
      #002677
      timeline.color.text.active-step-card.eyebrow.warning
      #C24E14
      timeline.color.text.active-step-card.heading.error
      #990000
      timeline.color.text.active-step-card.heading.info
      #126ECF
      timeline.color.text.active-step-card.heading.neutral
      #002677
      timeline.color.text.active-step-card.heading.warning
      #C24E14
      timeline.color.text.heading
      #002677
      timeline.color.text.paragraph
      #323334
      timeline.color.text.step.paragraph
      #4B4D4F
      timeline.color.text.step.heading.active.error
      #990000
      timeline.color.text.step.heading.active.info
      #126ECF
      timeline.color.text.step.heading.active.neutral
      #002677
      timeline.color.text.step.heading.active.warning
      #C24E14
      timeline.color.text.step.heading.default
      #323334
      timeline.color.text.step.timestamp.active.error
      #990000
      timeline.color.text.step.timestamp.active.info
      #126ECF
      timeline.color.text.step.timestamp.active.neutral
      #002677
      timeline.color.text.step.timestamp.active.warning
      #C24E14
      timeline.color.text.step.timestamp.default
      #323334
      timeline.border-radius.all.active-step-card.container
      12px
      timeline.border-radius.all.card.container
      12px
      timeline.border-radius.all.step.status-indicator
      500px
      timeline.border-radius.all.step.track.completed
      500px
      timeline.border-width.all.active-step-card.container
      1px
      timeline.border-width.all.card.container
      1px
      timeline.border-width.all.step.status-indicator
      1px
      timeline.border-width.all.step.track-dotted
      1px
      timeline.sizing.container.width.step.status-indicator.not-completed
      32px
      timeline.sizing.icon.all.icon.active-step-card.info-icon
      24px
      timeline.sizing.icon.all.step.info-icon
      16px
      timeline.sizing.icon.all.step.status-indicator
      24px
      timeline.spacing.gap.horizontal.active-step-card.buttons
      16px
      timeline.spacing.gap.horizontal.active-step-card.header
      16px
      timeline.spacing.gap.horizontal.step.container
      8px
      timeline.spacing.gap.horizontal.step.header
      4px
      timeline.spacing.gap.horizontal.step.timestamp
      4px
      timeline.spacing.gap.vertical.active-step-card.container
      16px
      timeline.spacing.gap.vertical.active-step-card.content
      8px
      timeline.spacing.gap.vertical.active-step-card.header
      4px
      timeline.spacing.gap.vertical.timeline.container
      16px
      timeline.spacing.gap.vertical.step.content
      12px
      timeline.spacing.gap.vertical.step.text
      4px
      timeline.spacing.padding.all.active-step-card.container
      16px
      timeline.spacing.padding.all.card.container
      16px
      timeline.spacing.padding.all.step.status-indicator
      4px
      timeline.spacing.padding.bottom.step.content
      24px
      timeline.spacing.padding.bottom.step.timestamp
      4px
      timeline.spacing.padding.vertical.step.status-indicator.not-completed
      4px
      Table of Contents