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.


  1. Accepted

    by John Smith

    11 Aug 2021

  2. Declined

    by John Smith

    10 Aug 2021

<div class="dwp-timeline">
<h1 class="govuk-heading-m">Appointments</h1>
<ol class="dwp-timeline__events">
<li class="dwp-timeline__events--entry">
  <h2 class="govuk-heading-s govuk-!-margin-bottom-1">Accepted</h2>
  <p class="govuk-caption-m govuk-!-margin-bottom-1">by John Smith</p>
  <p class="govuk-caption-m">11 Aug 2021</p>
<li class="dwp-timeline__events--entry">
  <h2 class="govuk-heading-s govuk-!-margin-bottom-1">Declined</h2>
  <p class="govuk-caption-m govuk-!-margin-bottom-1">by John Smith</p>
  <p class="govuk-caption-m">10 Aug 2021</p>
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
title string Required. The title that is displayed at the beginning of the timeline.
events array Required. An array of events ordered chronologically that are displayed on the timeline, see events
classes string Additional classes to add to the timeline
attributes object HTML Attributes (data attributes) to add to the timeline

Options for events array object

Name Type Description
name string Required. A descriptive name of the event
state string Required. The state of the event (for example, "booked")
date string Required. The date of the event
{% from "timeline/macro.njk" import dwpTimeline %}

        title: "Appointments",
        events: [
            name: "John Smith",
            state: "Accepted",
            date: "11 Aug 2021"
            name: "John Smith",
            state: "Declined",
            date: "10 Aug 2021"

When to use this component

Use the timeline component when you need to show a history of information or events that can be followed in chronological order.

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 should not be used to include and show large amounts of information.

You should not use the timeline component if you need to let users know where they are in a journey.

How it works

The timeline should display information in chronological order, with the newest item appearing at the top of the timeline.

Each entry in the timeline should include:

  • a short title that clearly explains what happened
  • who took the action
  • when the action was taken


This component has been used on services across DWP, including:

  • Manage Bereavement Support Payment
  • Access to work
  • Prepare for Universal Credit
  • Support for mortgage interest
  • Apply for New Style Jobseeker’s Allowance

The timeline has only been researched on agent-facing services. More research is needed on the component.

You can help to improve this pattern by:

Get in touch

If you’ve got a question, idea or suggestion email the Design System team on