Skip to contentSkip to navigationSkip to topbar
Paste
Paste assistant Assistant
FigmaStar

Timeline

Version 1.0.1GithubStorybook

A Timeline is a visual representation of events displayed in chronological order.

Component preview theme
const TimelineStart = () => {

  return (

    <Timeline>

      <TimelineItem title="Event title" timestamp="August 24, 2024">

        Event details

      </TimelineItem>

      <TimelineItem title="Event title" timestamp="August 29, 2024">

        Event details

      </TimelineItem>

      <TimelineItem title="Event title" timestamp="August 30, 2024">

        Event details

      </TimelineItem>

    </Timeline>

  );

};

render(<TimelineStart/>)

Guidelines

Guidelines page anchor

About Timeline

About Timeline page anchor

A Timeline can be used to display historical, current or future events or information in chronological order based on when they happened or are scheduled to happen.

Timelines can be used in different use cases, such as tracking milestones, monitoring system logs, or visualizing user activity.

Accessibility

Accessibility page anchor
  • Timeline is an ordered list (<ol>) and TimelineItem is a list item (<li>).
  • The only tabbable and interactive part of a Timeline is the toggle button when using the collapsible prop
    • collapsible TimelineItems use the Summary Detail component. The toggle button is labeled by the value of the timestamp prop. If the value is too verbose for a screen reader or not a clear label for the collapsed content, provide a helpful label for the button using the collapsibleLabelText prop on TimelineItem
  • Don’t use icons in TimelineItem markers to represent status like warning, error, or success. Since the marker is non-interactive, relying on icons for semantic meaning can cause accessibility challenges, particularly for people using screen readers.

Progress Steps vs Ordered Display List vs Timeline

Progress Steps vs Ordered Display List vs Timeline page anchor

Progress Steps

  • Progress Steps show users an outline of a complex multi-step task across multiple pages or apps.
  • Progress Steps convey progression and have interactive status states.

Ordered Display List

Ordered Display Lists structure tasks but don’t show progression or status through a multi-step task.

Timeline

  • Timeline displays the history or sequence of events, focusing on what has happened over time.
  • Use Timeline when user interaction is secondary, and progress does not depend on user actions since the process continues even without direct user input.

Examples

Examples page anchor

Timeline

Timeline page anchor

Use a basic Timeline as the default option to display a series of events that need to be ordered by time.

Component preview theme
const TimelineBasic = () => {

  return (

    <Timeline>

      <TimelineItem title="$0" timestamp="From March 6 - April 6, 2024">

      </TimelineItem>

      <TimelineItem title="$80" timestamp="From April 6 - April 30, 2024">

      </TimelineItem>

      <TimelineItem title="$199" timestamp="From April 6 - April 30, 2024">

        <Box display="flex" flexDirection="column" rowGap="space30" marginTop="space20">

          <StatusBadge as="span" variant="ProcessInProgress">

            In-progress

          </StatusBadge>

          <Paragraph marginBottom="space0">Auto renew every month until cancelled</Paragraph>

        </Box>

      </TimelineItem>

    </Timeline>

  );

};

render(<TimelineBasic/>)

Timeline with icons

Timeline with icons page anchor

Use a Timeline with icons to highlight events that would benefit from a visual cue to make the event more noticeable. Timeline icons are decorative, so they should not convey any information that is not clear from the text alone. Do not use icons to convey status or state.

Provide the TimelineItem with an icon prop to display an icon instead of the default dot. You must import the icon before passing it to the icon prop. The icon must be a Paste Icon. Icons passed to TimelineItems within a TimelineItemGroup will be ignored, as only direct children of the Timeline component should have visual markers.

(information)

Tip: Combine icons with dots to visually emphasize specific events within the Timeline.

Component preview theme
const TimelineIcon = () => {

  return (

    <Timeline>

      <TimelineItem title="Message created" timestamp="August 10, 2024 | 12:38 pm | 0 s" icon={SMSCapableIcon}>

        Twilio Platform

      </TimelineItem>

      <TimelineItem title="Enqueued" timestamp="August 10, 2024 | 12:38 pm | 0.04 s">

        Twilio Platform

      </TimelineItem>

      <TimelineItem title="Dequeued" timestamp="August 10, 2024 | 12:38 pm | 0.09 s">

        Twilio Platform

      </TimelineItem>

      <TimelineItem title="Sent" timestamp="August 10, 2024 | 12:38 pm | 0.20 s" icon={SentIcon}>

        Twilio Platform

      </TimelineItem>

      <TimelineItem title="Undelivered" timestamp="August 10, 2024 | 12:38 pm | 0.24 s" icon={DisableIcon}>

        Twilio Platform

      </TimelineItem>

    </Timeline>

  );

};

render(<TimelineIcon/>)

Collapsible Timeline content

Collapsible Timeline content page anchor

Use the collapsible prop when your Timeline includes additional information that doesn't need to be visible at all times.

Component preview theme
const TimelineCollapsible = () => {

  return (

    <Timeline>

      <TimelineItem title="Inbound call" timestamp="Yesterday | 9:11am | 5m 6s" icon={CallIcon} collapsible>

        Twilio Platform

      </TimelineItem>

      <TimelineItem title="Inbound SMS" timestamp="August 10, 2024 | 12:38 pm | 15m 34s" icon={SMSIcon} collapsible>

        <Box

          display="flex"

          rowGap="space30"

          columnGap="space30"

          flexWrap="wrap"

          color="colorTextWeak"

          fontWeight="fontWeightMedium"

          lineHeight="lineHeight20"

          fontSize="fontSize20">

          <Box display="flex" columnGap="space30">

            <AgentIcon decorative={true} />

            <Box>

              <Box as="span" fontWeight="fontWeightSemibold">

                Agent:{" "}

              </Box>

              Lizbeth Sarvati

            </Box>

          </Box>

          <Box display="flex" columnGap="space30">

            <NotesIcon decorative={true} />

            <Box>

              <Box as="span" fontWeight="fontWeightSemibold">

                Queue:{" "}

              </Box>

              Promo inbounds

            </Box>

          </Box>

          <Box display="flex" columnGap="space30">

            <Box display="flex" columnGap="space30">

              <SentimentPositiveIcon decorative={true} />

              <Box>

                <Box as="span" fontWeight="fontWeightSemibold">

                  Sentiment:{" "}

                </Box>

                Lizbeth Sarvati

              </Box>

            </Box>

            <Box display="flex" columnGap="space30">

              <SupportIcon decorative={true} />

              <Box>

                <Box as="span" fontWeight="fontWeightSemibold">

                  Disposition code:{" "}

                </Box>

                Promo inquiry

              </Box>

            </Box>

          </Box>

          <Box display="flex" columnGap="space30">

            <DocumentationIcon decorative={true} />

            <Box>

              <Box as="span" fontWeight="fontWeightSemibold">

                Agent:{" "}

              </Box>

              Ana received a $555 promotion on her phone and was interested in learning more about it.

              She was curious if she would be eligible for the promotion by increasing her deposits by $5,000 over the next two months.

              The agent explained that this was possible and suggested that she accept the offer through her app.

            </Box>

          </Box>

        </Box>

      </TimelineItem>

      <TimelineItem title="Campaign card viewed" timestamp="August 10, 2024 | 12:34 pm" icon={StarIcon} collapsible>

        <Box

          display="flex"

          flexDirection="column"

          rowGap="space30"

          as="span"

          color="colorTextWeak"

          fontWeight="fontWeightMedium"

          lineHeight="lineHeight20"

          fontSize="fontSize20">

          <Box>

            <Box as="span" fontWeight="fontWeightSemibold">

              Campaign:{" "}

            </Box>

            Earn $555 promotion

          </Box>

           <Box>

            <Box as="span" fontWeight="fontWeightSemibold">

              ID:{" "}

            </Box>

            WB-W-555-PROMO

          </Box>

        </Box>

      </TimelineItem>

      <TimelineItem title="Registered Visa Debit Card" timestamp="July 20, 2024 | 10:38 pm" icon={PaymentIcon} collapsible>

        Twilio Platform

      </TimelineItem>

    </Timeline>

  );

};

render(<TimelineCollapsible/>)

Grouped Timeline

Grouped Timeline page anchor

Use when multiple events happen at the same time or can be grouped under a common category to make the Timeline clearer.

(information)

It is not required to group all events that occur with the same timestamp. Grouping should be used when it enhances clarity, particularly when the events are part of the same logical sequence or related set of actions that match the user's mental model.

In a grouped Timeline, the timestamp is optional for individual Timeline items since they share a common timestamp. However, for collapsible Timeline items, if no timestamp is provided, a heading must be included as the collapsible header.

Component preview theme
const TimelineGrouped = () => {

  return (

    <Timeline>

      <TimelineItemGroup timestamp="September 17, 2024" icon={CalendarIcon}>

        <TimelineItem title="Filter Pattern">

          <Box display="flex" flexDirection="column" rowGap="space30" marginTop="space20">

            <StatusBadge as="span" variant="ProcessInProgress">

              In-progress

            </StatusBadge>

            <Paragraph marginBottom="space0">Filters enable users to narrow down and refine results across various types of content pages,

            including rich content pages, data tables, lists, data insights, and more.</Paragraph>

          </Box>

        </TimelineItem>

        <TimelineItem title="Timeline component">

          <Box display="flex" flexDirection="column" rowGap="space30" marginTop="space20">

            <StatusBadge as="span" variant="ProcessInProgress">

              In-progress

            </StatusBadge>

            <Paragraph marginBottom="space0">A component used to display a list of events that occurred in chronological order.</Paragraph>

          </Box>

        </TimelineItem>

      </TimelineItemGroup>

      <TimelineItemGroup timestamp="November 17, 2024" icon={CalendarIcon}>

        <TimelineItem title="Callout component, refined">

          <Box marginTop="space20">

            <StatusBadge as="span" variant="ProcessDraft">

              To do

            </StatusBadge>

          </Box>

        </TimelineItem>

      </TimelineItemGroup>

      <TimelineItem title="Pricing cards" icon={CalendarIcon} collapsible collapsibleHeading="More details">

        <Paragraph marginBottom="space0">The delivery timeline for the Pricing Pattern is pending approval from the broader team.</Paragraph>

      </TimelineItem>

    </Timeline>

  );

};

render(<TimelineGrouped/>)

Timeline event loading

Timeline event loading page anchor

Load more

Load more page anchor

Use a “Load more” Button in the Timeline when the screen viewport is limited. The events should load in batches of the same number of events that were initially displayed, once all the events have been displayed, remove the “Load more” Button.

Infinite scroll

Infinite scroll page anchor

Use infinite scroll only when the Timeline is the last item on the page or surface, and there are no footers or other elements below it that the user needs to interact with. Use Skeleton Loader for results that might take a while to load.

(information)

Tip: For very long Timelines, where pressing "Load more" Buttons might become cumbersome, consider using a Side Modal with infinite scroll to display the complete list of events.

a demo page with filter pattern

Composition notes

Composition notes page anchor

A Timeline should be presented in chronological order. The order can either be descending (most recent event at the top the list) or ascending (oldest event at the top of the list)

Use descending order on a Timeline when the current event is the most relevant information for the user.

  • Time sensitive information, for example an SMS sending tracker where the final status (sent or failed) is crucial for the user to track in real time.
  • Long lists of events that are constantly updated, for example in customer call logs where the most recent interaction is displayed first so agents can access the information in a timely manner.

Use ascending order on a Timeline when understanding the progression from the oldest event to the most recent is essential.

  • Diagnosing an issue, for example in platform issue reporting, where understanding the sequence of reported issues is necessary to understand the problem.
  • Events that evolve through time, for example in payment history where the price has changed over time.

Any content and other components can be placed within the Timeline item detail.

Component preview theme
const TimelineComposition = () => {

  return (

    <Timeline>

      <TimelineItem title="Message sent" timestamp="August 24, 2024">

       <Box marginTop="space20">

          <Paragraph marginBottom="space0">The message was successfully sent through the following diffusion channels:</Paragraph>

          <Box marginTop="space30">

            <Table>

              <THead>

                <Tr>

                  <Th>Channel Name</Th>

                  <Th>Status</Th>

                </Tr>

              </THead>

              <TBody>

                <Tr>

                  <Td>

                    Customer Updates

                  </Td>

                  <Td>

                    <StatusBadge as="span" variant="ProcessSuccess">

                      Sent

                    </StatusBadge>

                  </Td>

                </Tr>

                <Tr>

                  <Td>

                   Special Promotions

                  </Td>

                  <Td>

                    <StatusBadge as="span" variant="ProcessSuccess">

                      Sent

                    </StatusBadge>

                  </Td>

                </Tr>

              </TBody>

            </Table>

          </Box>

        </Box>

      </TimelineItem>

      <TimelineItem title="Message scheduled" timestamp="August 22, 2024">

        <Box marginTop="space10">

          <Paragraph marginBottom="space0">The message has been scheduled for delivery.</Paragraph>

          <Anchor href="#" display="block" marginTop="space50">

            View Scheduled Message

          </Anchor>

        </Box>

      </TimelineItem>

      <TimelineItem title="Message created" timestamp="August 20, 2024">

        <Box marginTop="space20">

          <StatusBadge as="span" variant="ProcessSuccess">

            Completed

          </StatusBadge>

        </Box>

      </TimelineItem>

    </Timeline>

  );

};

render(<TimelineComposition/>)

Timestamp

Timestamp page anchor

Follow Paste's date guidelines and time guidelines to format the timestamp for each Timeline item. In use cases where more than one timestamp per Timeline item is required, use separators in between timestamps for clarity. Order multiple timestamps by starting with the largest time unit and ending with the smallest:

  1. Month and Day, Year (ex: "August 10, 2024")
  2. Hour, Minute, Second (ex: "12:38 pm")
  3. Additional Details (ex: "0.2 s" for duration)
Component preview theme
const TimelineTimestamp = () => {

  return (

    <Timeline>

      <TimelineItem title="Flagged on Verizon" timestamp="August 10, 2024 | 12:38:00 pm">

       <Box marginTop="space20">

          <StatusBadge as="span" variant="ProcessWarning">

            Warning

          </StatusBadge>

        </Box>

      </TimelineItem>

      <TimelineItem title="Unflagged on AT&T" timestamp="August 10, 2024 | 12:38:02 pm">

        <Box marginTop="space20">

          <StatusBadge as="span" variant="ProcessSuccess">

            Success

          </StatusBadge>

        </Box>

      </TimelineItem>

      <TimelineItem title="Flagged on AT&T" timestamp="August 10, 2024 | 12:38:03 pm">

        <Box marginTop="space20">

          <StatusBadge as="span" variant="ProcessWarning">

            Warning

          </StatusBadge>

        </Box>

      </TimelineItem>

    </Timeline>

  );

};

render(<TimelineTimestamp/>)

Dos and don'ts

Dos and don'ts page anchor
  1. Event titleAugust 30, 2024
  2. Event titleAugust 29, 2024
  3. Event titleAugust 21, 2024
Do

Always include a timestamp on Timeline events.

  1. Sign upAugust 30, 2024
  2. Validate emailAugust 29, 2024
  3. Complete profileAugust 21, 2024
Don't

Don’t use Timeline as a way of navigating tasks.

  1. FlaggedAugust 30, 2024
    Warning
  2. SentAugust 29, 2024
    Success
Do

For use cases where displaying status is beneficial to the user, you can incorporate Status Badges or other status components within the Timeline item content.

  1. SendingAugust 30, 2024
  2. UndeliveredAugust 29, 2024
Don't

Don’t use icons as Timeline item markers to represent status like warning, error, or success.