Components Timeline

Use the timeline component to show a linear record of what has happened.

The timeline component has only been researched on agent-facing services.

2024 update

In August 2024 we redesigned the Timeline component. The new version of the component is included in DWP Frontend version 3 and later.

The main changes are:

  • events can now include links and descriptions
  • $govuk-text-colour replaces $govuk-secondary-text-colour for improved contrast
  • date is now shown first and aligned to the timeline marker
  • there is an end marker to show the end of the timeline (below the earliest event)
Important: This is a breaking change. If your service includes an earlier version of the Timeline component you will need to update your code.
Open this appointments timeline example in a new tab

Events

  1. 16 June 2024 at 1:00am

    Completed ‘DP224JP’ form received

    by System

  2. 1 June 2024 at 7:14am

    Summary of report including recommendations, suppliers and costs sent to claimant

    by John Goldsmith

  3. 15 May 2024 at 4:01pm

    Workplace assessment report

    by John Goldsmith

    View details of the event on 15 May 2024 at 4:01pm

  4. 26 April 2024 at 12:42pm

    Workplace assessment

    by John Goldsmith

    Agreed with the claimant that a workplace assessment is required and confirmed assessor visit on 5 May 2024 at 9:45am – confirmation letter sent

  5. 21 April 2024 at 1:12pm

    Update to: Health condition or disability

    by Jane Doe

    View details of the event on 21 April 2024 at 1:12pm

  6. 21 April 2024 at 10:15am

    Telephone call made

    by Jane Doe

    A telephone call was made to the claimant requesting further information to support the claim

    View details of the event on 21 April 2024 at 10:15am

  7. 19 April 2024 at 10:58am

    Text message (SMS) sent

    by Jane Doe

    SMS was sent to the claimant to inform them that we require further information and will be in contact on 21 April 2024

  8. 16 April 2024 at 9:00am

    Health condition or disability

    by Jane Doe

    Contact needed for more information

  9. 28 March 2024 at 9:12am

    Check personal details and add National Insurance number task

    by Jane Doe

  10. 12 March 2024 at 3:00pm

    Application received

<h1 class="govuk-heading-l">Events</h1>
<div class="dwp-timeline">
<ol class="dwp-timeline__items">
<li class="dwp-timeline__item">
  <p class="dwp-timeline__datetime">16 June 2024 at 1:00am</p>
  <h2 class="dwp-timeline__heading">Completed ‘DP224JP’ form received</h2>
  <p class="dwp-timeline__by-line">by System</p>
</li>
<li class="dwp-timeline__item">
  <p class="dwp-timeline__datetime">1 June 2024 at 7:14am</p>
  <h2 class="dwp-timeline__heading">Summary of report including recommendations, suppliers and costs sent to claimant</h2>
  <p class="dwp-timeline__by-line">by John Goldsmith</p>
</li>
<li class="dwp-timeline__item">
  <p class="dwp-timeline__datetime">15 May 2024 at 4:01pm</p>
  <h2 class="dwp-timeline__heading">Workplace assessment report</h2>
  <p class="dwp-timeline__by-line">by John Goldsmith</p>
  <a href="#" class="dwp-timeline__link">View details<span class="govuk-visually-hidden"> of the event on 15 May 2024 at 4:01pm</span></a>
</li>
<li class="dwp-timeline__item">
  <p class="dwp-timeline__datetime">26 April 2024 at 12:42pm</p>
  <h2 class="dwp-timeline__heading">Workplace assessment</h2>
  <p class="dwp-timeline__by-line">by John Goldsmith</p>
  <p class="dwp-timeline__content">Agreed with the claimant that a workplace assessment is required and confirmed assessor visit on 5 May 2024 at 9:45am – confirmation letter sent</p>
</li>
<li class="dwp-timeline__item">
  <p class="dwp-timeline__datetime">21 April 2024 at 1:12pm</p>
  <h2 class="dwp-timeline__heading">Update to: Health condition or disability</h2>
  <p class="dwp-timeline__by-line">by Jane Doe</p>
  <a href="#" class="dwp-timeline__link">View details<span class="govuk-visually-hidden"> of the event on 21 April 2024 at 1:12pm</span></a>
</li>
<li class="dwp-timeline__item">
  <p class="dwp-timeline__datetime">21 April 2024 at 10:15am</p>
  <h2 class="dwp-timeline__heading">Telephone call made</h2>
  <p class="dwp-timeline__by-line">by Jane Doe</p>
  <p class="dwp-timeline__content">A telephone call was made to the claimant requesting further information to support the claim</p>
  <a href="#" class="dwp-timeline__link">View details<span class="govuk-visually-hidden"> of the event on 21 April 2024 at 10:15am</span></a>
</li>
<li class="dwp-timeline__item">
  <p class="dwp-timeline__datetime">19 April 2024 at 10:58am</p>
  <h2 class="dwp-timeline__heading">Text message (SMS) sent</h2>
  <p class="dwp-timeline__by-line">by Jane Doe</p>
  <p class="dwp-timeline__content">SMS was sent to the claimant to inform them that we require further information and will be in contact on 21 April 2024</p>
</li>
<li class="dwp-timeline__item">
  <p class="dwp-timeline__datetime">16 April 2024 at 9:00am</p>
  <h2 class="dwp-timeline__heading">Health condition or disability </h2>
  <p class="dwp-timeline__by-line">by Jane Doe</p>
  <p class="dwp-timeline__content">Contact needed for more information</p>
</li>
<li class="dwp-timeline__item">
  <p class="dwp-timeline__datetime">28 March 2024 at 9:12am</p>
  <h2 class="dwp-timeline__heading">Check personal details and add National Insurance number task</h2>
  <p class="dwp-timeline__by-line">by Jane Doe</p>
</li>
<li class="dwp-timeline__item">
  <p class="dwp-timeline__datetime">12 March 2024 at 3:00pm</p>
  <h2 class="dwp-timeline__heading">Application received</h2>
</li>
</ol>
</div>
Nunjucks macro options

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

Some options are required for the macro to work; these are marked as “Required” in the option description.

If you’re using Nunjucks macros in production with “html” options, or ones ending with “html”, you must sanitise the HTML to protect against cross-site scripting exploits.

Name Type Description
items array An array of items ordered chronologically that are displayed on the timeline, see items
headingLevel string Allows you to change the heading level of the item header, defaults to an h2
classes string Additional classes to add to the timeline
attributes object HTML Attributes (data attributes) to add to the timeline

Options for items array object

Name Type Description
date string The date and time of the item
title string Required. The title of the item
byline string Required. Who or what produced the item
description object Description of the item, see items description
link object The date of the event, see items link

Options for items description object

Name Type Description
text string If text is set, this is not required. HTML to use within the item label. If html is provided, the text argument will be ignored.
html string If html is set, this is not required. Text to use within the item label. If html is provided, the text argument will be ignored.
Name Type Description
href string Value of the link’s href attribute for an item link.
text string Text to use within links link item.
visuallyHiddenText string Addtional text added to the link to give context 
{% from "timeline/macro.njk" import dwpTimeline %}

<h1 class="govuk-heading-l">Events</h1>
{{
    dwpTimeline({ 
        items: [
            {
                title:  "Completed ‘DP224JP’ form received",
                byline:  "System",
                date:  "16 June 2024 at 1:00am"
            },
          
            {
                title:  "Summary of report including recommendations, suppliers and costs sent to claimant",
                byline:  "John Goldsmith",
                date:  "1 June 2024 at 7:14am"
            },
            {
                title:  "Workplace assessment report",
                byline:  "John Goldsmith",
                link: {
                    href: "#",
                    text: "View details",
                    visuallyHiddenText: "of the event on 15 May 2024 at 4:01pm"
                },
                date:  "15 May 2024 at 4:01pm"
            },
           
           
            {
                title:  "Workplace assessment",
                byline:  "John Goldsmith",
                description: {
                    text: "Agreed with the claimant that a workplace assessment is required and confirmed assessor visit on 5 May 2024 at 9:45am – confirmation letter sent"
                },
                date:  "26 April 2024 at 12:42pm"
            },
           
          
            {
                title:  "Update to: Health condition or disability",
                byline:  "Jane Doe",
                link: {
                    href: "#",
                    text: "View details",
                    visuallyHiddenText: "of the event on 21 April 2024 at 1:12pm"
                },
                date:  "21 April 2024 at 1:12pm"
            },
            {
                title:  "Telephone call made",
                byline:  "Jane Doe",
                description: {
                    text: "A telephone call was made to the claimant requesting further information to support the claim"
                },
                link: {
                    href: "#",
                    text: "View details",
                    visuallyHiddenText: "of the event on 21 April 2024 at 10:15am"
                },
                date:  "21 April 2024 at 10:15am"
            },
            {
                title:  "Text message (SMS) sent",
                byline:  "Jane Doe",
                description: {
                    text: "SMS was sent to the claimant to inform them that we require further information and will be in contact on 21 April 2024"
                },
                date:  "19 April 2024 at 10:58am"
            },
         
         
            {
                title:  "Health condition or disability ",
                byline:  "Jane Doe",
                description: {
                    text: "Contact needed for more information"
                },
                date:  "16 April 2024 at 9:00am"
            },
           
            {
                title:  "Check personal details and add National Insurance number task",
                byline:  "Jane Doe",
                date:  "28 March 2024 at 9:12am"
            },
            {
                title:  "Application received",
                date:  "12 March 2024 at 3:00pm"
            }
    ]
    })
}}

When to use this component

Use the timeline component when you need to display a record of events (or other information) in time order: for example, a history of actions taken on a particular case.

The timeline should show a brief overview of what has happened at each point and should not be used to give in-depth information.

When not to use this component

The timeline is designed as a way of presenting static information, not as a working environment. Do not use it as a container for important tasks or work, as navigation for your service, or as a progress indicator.

Do not use the description to contain full details of an event or large amounts of text: this should be shown in a separate place and linked to if necessary.

How it works

The timeline displays information in reverse chronological order, with the newest item appearing at the top of the list.

In its simplest form each timeline entry includes:

  • date and time
  • title

Optionally entries can also include:

  • byline (the person or system that did the action)
  • description
  • link

Content elements

Date and time

This is the basic functional element of the timeline and lines up with the marker on the timeline itself.

Use GOV.UK style for dates and times: 4 June 2025 at 9:30am.

  • Dates: day, month and year with no ordinal indicators: 4 June, not 4th June
  • Times: 12-hour clock with am and pm, no leading numerals, a colon separating hours and minutes followed by am or pm without a space: 9:30am, not 0930 or 09.30 am

You should transform data into this format for presentation even if it comes from another system in a different format. Times in 24-hour format or with leading zeroes can be more difficult to read for users with dyslexia or dyscalculia.

Title

What has happened: this could be taken from a standard list of event types or could be manually entered by agents.

Byline

The person or system that did the action. This is useful if more than one person can work on a case, or if your timeline includes both agent actions and automated events.

Description

Brief details of the event, if necessary. This information gives additional summary information if it is useful. It can be generated by a system or entered as comments by a user.

Do not use the description to contain full details of an event or large amounts of text: this should be shown in a separate place and linked to if necessary.

An event can include a text link to more detailed information. This link does not reveal content in the timeline itself; instead it takes the user to the information in another page or interface. This maintains the position of other timeline items and avoids overcrowding the interface with additional detail.

It is important for the usability of the timeline that events are simple and consistent in their appearance. Do not use any interactive elements other than the single text link – no accordions, details components or buttons.

If you use the same anchor text for all links – as with “View details” in our example – you must take steps to make the links distinct so they are accessible.

In our example we use hidden text to include the date and time of each event. Your solution will depend on your implementation of the component and the structure of your source data.

Technical guidance

The updated Timeline component is included in DWP Frontend version 3 and later.

This is a breaking change. If your service includes an earlier version of the component you will need to update your code.

Accessibility

If you repeat link text for more than one event, make sure that screen reader users can tell links apart: for example, by including specific event details in hidden text.

If your back-end system produces time information in 24-hour format, transform it to the correct 12-hour format for presentation in the timeline. Times in 24-hour format or with leading zeroes can be more difficult to read for users with dyslexia or dyscalculia.

For more about building accessible services see the DWP Accessibility Manual.

Research

The previous version of this component has been used in a number of agent-facing DWP services: we have worked with to those teams to understand their needs for the updated component but need more research insights from live services.

Contribute

If you have used or researched this component, please let us know what you found so we can make it better for everyone. There is an open discussion on GitHub where you can share anything you think might be useful.

Get in touch

If you’ve got a question, idea or suggestion email the Design System team on dwp-design-system@engineering.digital.dwp.gov.uk