Skip to main content
Back

Timeline

This pattern helps users understand what has happened and when. For example, the history of a tax repayment claim.

When to use

Use this pattern to show a list of entries in the order they happened.

When not to use

Do not use this pattern to let users know where they are in a journey.

How it works

You need HMRC Frontend to use this pattern — find out how to install HMRC Frontend. If you use the HMRC Nunjucks macro, you must copy and paste the entire macro into your code.

Each item in the timeline should have:

  • a title
  • the date and/or time

You could also include a brief description, but this is optional.

              <ol class="hmrc-timeline">
  <li class="hmrc-timeline__event">
    <h2 class="hmrc-timeline__event-title">Repayment complete</h2>
    <time class="hmrc-timeline__event-meta" datetime="2020-07-15">15 July 2020</time>
    <div class="hmrc-timeline__event-content">
      <p class="govuk-body">We repaid you £50. It will take 3 days for the money to reach your account.</p>
    </div>
  </li>
  <li class="hmrc-timeline__event">
    <h2 class="hmrc-timeline__event-title">Checking your claim</h2>
    <time class="hmrc-timeline__event-meta" datetime="2020-07-14">14 July 2020</time>
    <div class="hmrc-timeline__event-content">
      <p class="govuk-body">We received your return. You claimed you were due a repayment of £50. We are checking your claim.</p>
    </div>
  </li>
</ol>
            
                <ol class="hmrc-timeline">
  <li class="hmrc-timeline__event">
    <h2 class="hmrc-timeline__event-title">Ad-daliad wedi’i wneud</h2>
    <time class="hmrc-timeline__event-meta" datetime="2020-07-15">15 Gorffennaf 2020</time>
    <div class="hmrc-timeline__event-content">
      <p class="govuk-body">Gwnaethom ad-dalu £50 i chi. Bydd yn cymryd hyd at 3 diwrnod i'r arian gyrraedd eich cyfrif.</p>
    </div>
  </li>
  <li class="hmrc-timeline__event">
    <h2 class="hmrc-timeline__event-title">Gwirio’ch hawliad</h2>
    <time class="hmrc-timeline__event-meta" datetime="2020-07-14">14 Gorffennaf 2020</time>
    <div class="hmrc-timeline__event-content">
      <p class="govuk-body">Daeth eich Ffurflen Dreth i law. Gwnaethoch honni bod ad-daliad o £50 yn ddyledus i chi. Rydym yn gwirio’ch hawliad.</p>
    </div>
  </li>
</ol>
              
                {%- from "hmrc/components/timeline/macro.njk" import hmrcTimeline -%}

{% set exampleContent1 %}<p class="govuk-body">We received your return. You claimed you were due a repayment of £50. We are checking your claim.</p>{% endset %}
{% set exampleContent2 %}<p class="govuk-body">We repaid you £50. It will take 3 days for the money to reach your account.</p>{% endset %}

  {{ hmrcTimeline({
    headingLevel: "2",
    events: [
      {
        title: 'Repayment complete',
        datetime: '2020-07-15',
        time: '15 July 2020',
        content: exampleContent2
      },
      {
        title: 'Checking your claim',
        datetime: '2020-07-14',
        time: '14 July 2020',
        content: exampleContent1
      }
    ]
  }) }}
              
                  {%- from "hmrc/components/timeline/macro.njk" import hmrcTimeline -%}

{% set exampleContent1 %}<p class="govuk-body">Daeth eich Ffurflen Dreth i law. Gwnaethoch honni bod ad-daliad o £50 yn ddyledus i chi. Rydym yn gwirio’ch hawliad.</p>{% endset %}
{% set exampleContent2 %}<p class="govuk-body">Gwnaethom ad-dalu £50 i chi. Bydd yn cymryd hyd at 3 diwrnod i'r arian gyrraedd eich cyfrif.</p>{% endset %}

  {{ hmrcTimeline({
    headingLevel: "2",
    events: [
      {
        title: 'Ad-daliad wedi’i wneud',
        datetime: '2020-07-15',
        time: '15 Gorffennaf 2020',
        content: exampleContent2
      },
      {
        title: 'Gwirio’ch hawliad',
        datetime: '2020-07-14',
        time: '14 Gorffennaf 2020',
        content: exampleContent1
      }
    ]
  }) }}
                

Research

The pattern is used in the VAT repayments service. Usability testing took place with 7 users as part of 3 rounds of research.

The rearch showed that users understood that the:

  • all the events were related to each other
  • each event followed a previous event
  • the top event was the most recent one

We need more research. If you have used the Timeline pattern, get in touch to share your research findings.

Discuss Timeline on GitHub