Skip to main content

Timeline

Displays a list of content in chronological order.

Submit feedback
Edit this page
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. 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'.

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

      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.

      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

      NameTypeDefaultRequiredDescription
      activeStep
      number
      		-
      The 1-indexed active step number
      activeStepCompletionState
      "completed" | "in-progress"
      'in-progress'
      		-
      The completion state of the active step
      cardConfig
      Pick<ActiveStepCardProps, "ariaText" | "headingLevel" | "helper" | "description" | "extraContent" | "buttons"> | never
      		--
      Configuration for the active step card
      Configuration for the Timeline card
      children
      React.ReactNode
      		--
      The steps to display in the Timeline
      className
      string
      		--
      CSS class name to apply to each element within the component
      css
      Abyss.CSSProperties | Partial<Record<`abyss-${T}`, Abyss.CSSProperties>>
      		--
      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
      		--
      Suffix used to create a unique ID used for automated testing
      See Component Testing for more information
      disableDefaultProviderProps
      boolean
      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
      React.ReactNode
      		--
      Extra content to display below the Timeline
      headingLevel
      1 | 2 | 3 | 4 | 5 | 6
      3
      		-
      The heading level for the title
      title
      string
      'Timeline history'
      		-
      The title of the Timeline
      type
      "card" | "simple"
      'card'
      		-
      The Timeline type

      Below are the link(s) to the relevant GitHub type files:

      Abyss.d.ts

      Timeline.Step Props

      NameTypeDefaultRequiredDescription
      ariaText
      string
      		--
      If present, this value will be added as hidden text on the step status icon for screen readers
      button
      TimelineStepButton
      		--
      If present, the step will display a button
      className
      string
      		--
      CSS class name to apply to each element within the component
      css
      Abyss.CSSProperties | Partial<Record<`abyss-${T}`, Abyss.CSSProperties>>
      		--
      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
      		--
      Suffix used to create a unique ID used for automated testing
      See Component Testing for more information
      date
      string
      		--
      The step's date
      description
      string
      		--
      The step's description
      disableDefaultProviderProps
      boolean
      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
      React.ReactNode
      		--
      Helper element next to step title
      hideCompletionState
      boolean
      false
      		-
      If true, the step completion state will not be displayed
      status
      "neutral" | "error" | "info" | "warning"
      'neutral'
      		-
      The step's status
      title
      string
      		-
      The step's title

      Below are the link(s) to the relevant GitHub type files:

      Abyss.d.ts

      Timeline Classes

      Class NameDescription
      .abyss-timeline-rootTimeline root element
      .abyss-timeline-headerTimeline header element
      .abyss-timeline-headingTimeline heading element
      .abyss-timeline-step-countTimeline step count element
      .abyss-timeline-step-containerTimeline step container element
      .abyss-timeline-extra-content-containerTimeline active step card extra content container
      .abyss-timeline-card-rootTimeline card root element
      .abyss-timeline-active-step-card-rootTimeline active step card root element
      .abyss-timeline-active-step-card-contentTimeline active step card content container
      .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-eyebrowTimeline active step card eyebrow text element
      .abyss-timeline-active-step-card-headingTimeline active step card heading text element
      .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-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-button-containerTimeline active step card button container
      .abyss-timeline-active-step-card-primary-buttonTimeline active step card primary button
      .abyss-timeline-active-step-card-secondary-buttonTimeline active step card secondary button

      Timeline.Step Classes

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

      Component Tokens

      Note: 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