Components
Timeline
Status: To be reviewedHow to use ‘to be reviewed’ components
Components with a ‘to be reviewed’ status have been added for use by everyone, but have not been checked or improved recently.
Read about all the Design System statuses.
Contents
<div class="moj-timeline">
<div class="moj-timeline__item">
<div class="moj-timeline__header">
<h2 class="moj-timeline__title">Application needs confirmation</h2>
<p class="moj-timeline__byline">by Joe Bloggs</p>
</div>
<p class="moj-timeline__date">
<time datetime="2026-06-14T14:01:00.000Z">14 June 2026 at 2:01pm</time>
</p>
<div class="moj-timeline__description">
<p>The probation practitioner's application for life skills training needs confirming by 28 June 2026.<a class="govuk-link" href="#">
View application
<span class="govuk-visually-hidden">
for life skills training submitted on 28 May 2026
</span>
</a></p>
</div>
</div>
<div class="moj-timeline__item">
<div class="moj-timeline__header">
<h2 class="moj-timeline__title">Application review in progress</h2>
<p class="moj-timeline__byline">by Caseworker 1</p>
</div>
<p class="moj-timeline__date">
<time datetime="2026-06-07T12:32:00.000Z">7 June 2026 at 12:32pm</time>
</p>
<div class="moj-timeline__description">The application is being reviewed by a case worker.</div>
</div>
<div class="moj-timeline__item">
<div class="moj-timeline__header">
<h2 class="moj-timeline__title">Application received</h2>
<p class="moj-timeline__byline">by Caseworker 1</p>
</div>
<p class="moj-timeline__date">
<time datetime="2026-06-06T09:12:00.000Z">6 June 2026 at 9:12am</time>
</p>
<div class="moj-timeline__description">Your application has been received – reference MOJ-1234-5678</div>
</div>
<div class="moj-timeline__item">
<div class="moj-timeline__header">
<h2 class="moj-timeline__title">Application submitted: life skills</h2>
<p class="moj-timeline__byline">by Joe Bloggs</p>
</div>
<p class="moj-timeline__date">
<time datetime="2026-05-28T10:45:00.000Z">28 May 2026 at 10:45am</time>
</p>
<div class="moj-timeline__description">
<details class="govuk-details govuk-!-margin-bottom-0">
<summary class="govuk-details__summary">
<span class="govuk-details__summary-text">
Application details
<span class="govuk-visually-hidden">
for application MOJ-1234-5678
</span>
</span>
</summary>
<div class="govuk-details__text">
This is an application for life skills training at Queensbridge centre, Gloucester. The course lasts 12 weeks. <a class="govuk-link" href="#">
View application
<span class="govuk-visually-hidden">
for life skills training submitted on 28 May 2026
</span>
</a>
</div>
</details>
</div>
</div>
<div class="moj-timeline__item">
<div class="moj-timeline__header">
<h2 class="moj-timeline__title">Application started</h2>
<p class="moj-timeline__byline">by Joe Bloggs</p>
</div>
<p class="moj-timeline__date">
<time datetime="2026-05-21T13:15:00.000Z">21 May 2026 at 1:15pm</time>
</p>
<div class="moj-timeline__description"></div>
</div>
</div>
Nunjucks macro options
Container
| Name | Type | Required | Description |
|---|---|---|---|
| classes | string | No | Classes to add to the timeline's container. |
| attributes | object | No | HTML attributes (for example data attributes) to add to the timeline's container. |
| headingLevel | numeric | No | A number for the heading level. Defaults to 2 (<h2>). |
Items
| Name | Type | Required | Description |
|---|---|---|---|
| label | object | Yes | See item label. |
| text | string | Yes | If html is set, this is not required. Text to use within the item. If html is provided, the text argument will be ignored. |
| html | string | Yes | If text is set, this is not required. HTML to use within the item. If html is provided, the text argument will be ignored. |
| datetime | object | No | See item datetime. |
| byline | object | No | See item byline. |
| classes | string | No | Classes to add to the timeline's items container. |
| attributes | object | No | HTML attributes (for example data attributes) to add to the timeline's items container. |
Item label
| Name | Type | Required | Description |
|---|---|---|---|
| text | string | Yes | 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. |
| html | string | Yes | 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. |
Item datetime
| Name | Type | Required | Description |
|---|---|---|---|
| timestamp | string | Yes | A valid datetime string to be formatted. For example: 1970-01-01T11:59:59.000Z |
| type | string | Yes | If format is set, this is not required. The standard date format to use within the item. If type is provided, the format argument will be ignored. Values include: datetime, shortdatetime, date, shortdate and time |
| format | string | Yes | If type is set, this is not required. The user-defined date format to use within the item. If type is provided, the format argument will be ignored. See the Moment.js document on display formats. |
Item byline
| Name | Type | Required | Description |
|---|---|---|---|
| text | string | Yes | If html is set, this is not required. Text to use within the item byline. If html is provided, the text argument will be ignored. |
| html | string | Yes | If text is set, this is not required. HTML to use within the item byline. If html is provided, the text argument will be ignored. |
Warning: If you’re using Nunjucks macros in production be aware that using HTML arguments, or ones ending with .html can be at risk from cross-site scripting attacks. More information about security vulnerabilities can be found in the Nunjucks documentation.
{%- from "moj/components/timeline/macro.njk" import mojTimeline -%}
{%- set confirmationHtml %}
<p>The probation practitioner's application for life skills training needs confirming by 28 June 2026.<a class="govuk-link" href="#">
View application
<span class="govuk-visually-hidden">
for life skills training submitted on 28 May 2026
</span>
</a></p>
{% endset -%}
{%- set detailsHtml %}
<details class="govuk-details govuk-!-margin-bottom-0">
<summary class="govuk-details__summary">
<span class="govuk-details__summary-text">
Application details
<span class="govuk-visually-hidden">
for application MOJ-1234-5678
</span>
</span>
</summary>
<div class="govuk-details__text">
This is an application for life skills training at Queensbridge centre, Gloucester. The course lasts 12 weeks. <a class="govuk-link" href="#">
View application
<span class="govuk-visually-hidden">
for life skills training submitted on 28 May 2026
</span>
</a>
</div>
</details>
{% endset -%}
{{ mojTimeline({
items: [
{
label: {
text: "Application needs confirmation"
},
html: confirmationHtml,
datetime: {
timestamp: "2026-06-14T14:01:00.000Z",
type: "datetime"
},
byline: {
text: "Joe Bloggs"
}
},
{
label: {
text: "Application review in progress"
},
text: "The application is being reviewed by a case worker.",
datetime: {
timestamp: "2026-06-07T12:32:00.000Z",
type: "datetime"
},
byline: {
text: "Caseworker 1"
}
},
{
label: {
text: "Application received"
},
text: "Your application has been received – reference MOJ-1234-5678",
datetime: {
timestamp: "2026-06-06T09:12:00.000Z",
type: "datetime"
},
byline: {
text: "Caseworker 1"
}
},
{
label: {
text: "Application submitted: life skills"
},
html: detailsHtml,
datetime: {
timestamp: "2026-05-28T10:45:00.000Z",
type: "datetime"
},
byline: {
text: "Joe Bloggs"
}
},
{
label: {
text: "Application started"
},
html: listHtml,
datetime: {
timestamp: "2026-05-21T13:15:00.000Z",
type: "datetime"
},
byline: {
text: "Joe Bloggs"
}
}
]
}) }}
This component is in the ‘Assets’ tab in the MOJ Figma Kit.
If you work for MOJ, you can view this component in the MOJ Figma Kit.
If you work outside MOJ, read the guidance on setting up Figma prototypes for non-MOJ staff.
Overview
The timeline shows users what has happened in a service, for example in a case, claim, or application. Each timeline item shows who added the information to the service, and when.
When to use
Use the timeline when people need to view:
- the history of a case or application
- events in date order
- updates from different people or systems in one place
When not to use
Do not use this component:
- as a task list
- as a progress indicator
- as navigation
- to display large amounts of information
Use the GOV.UK step by step navigation pattern to show users an end-to-end journey.
How to use
Show the most recent events first, unless user research suggests a different order is better.
What to include
Each item should include:
- a short title
- the date (or date and time)
- who or what made the update
Research will tell you what information is helpful for your users. You can also include:
- a short description
- a link to more detail
Timeline content
Item titles
Titles should be concise and descriptive, for example ‘Risk assessment completed’, ‘Evidence sent’, ‘Address needed’.
Item author
The author (called ‘byline’ in the code) shows who or what made the update, for example:
- ‘by Joe Bloggs’
- ‘by a staff member at HM Winchester’
- ‘by NDelius’
Date and time
To display the date and time use:
- GOV.UK guidance on dates
- GOV.UK guidance on times, for example ‘4 June 2026 at 9:32am’
- guidance on showing time in prison services, if your service is used by prison staff
If you cannot get the time for an event (for example, because it’s from a legacy system) just use the date. Do not display a default time, such as 00:00.
Item description
Item descriptions should be short – no longer than a few sentences. If there’s more information, link to another page.
Links in items
If you’re using the same link text more than once, use visually hidden text (such as an aria label) to differentiate the link descriptions. For example, add the hidden text ‘about address updated on 4 June 2025’ after the link text ‘View details’.
Get help and contribute
Get help
You can contact the MOJ Design System team for help or support using this component.
Help improve this component
The MOJ Design System team would like to hear:
- how you have used this component in your service
- any feedback you have about its usage, for example accessibility or ideas for improvement
Add these comments to the timeline discussion on GitHub.