Skip to main content



The Timeline component represents a sequence of events that happen within a process, and shows the status.

It gives an overview of the whole process and progress of a customer journey. Its main purpose is to create situational awareness for the user and manage expectations.

  • Provides the customer with visibility on the status of a process or system in their journey.
  • Gives a top-level overview of the process.
  • It's clear to understand and manages expectations by showing the current situation to the user.

Content guidance#

(Sequence shortened.)


Each event has a status. The status of the event is controlled by the decoration used.

pendingpendingCommunicates that the event has yet to commence.
in progressinprogressIndicates that progress is currently being made on this step.
successcompletedThe event has been successfully completed.
action requiredactionrequiredThis is used when a customer needs to take action in order to proceed with the process.
warningwarningInforms of a problem with low severity such as foreseeable delays or outages etc. The problem is expected to be automatically resolved as the situation changes.
errorerrorThis is a failure indication. Something couldn't be resolved and so has halted the whole process marking other inprogress\ pending event(s) cancelled. It should be accompanied by a helpful message.

Icons & numerals#

There are 3 styles of timeline to choose from in the 'overview decorations' - default, icon, or number.


Uses a circle and implies nothing other than it is an event.


Thes can be selected from a list to help convey meaning for each event and make it easier to identify a step. If selected, all events will need an icon chosen from the list.


For use when an order should be shown.

Some icons are special and automatically reserved for use only with a particular status, such as Complete tick, Action required arrow, Warning triangle, and Error diamond. These show on all the variants of 'overview decoration'.

Heading, summary and step count#

There is provision for a heading to describe what process the timeline is showing. This can be left blank if it has already been made clear in an ns-landmark above it to avoid duplication.

You can also add a summary to manage expectations

eg. 2 days until your appointment

In addition to this, you can also display information on the number of events using step count. You can have up to 10 steps in a process and show how many have been completed so far.

eg. 1 of 6 steps completed

Showing additional information#

On events that are in progress, it is possible to add further information relevant to this step to aid customer understanding, or if an action is required, provide a link to another area such as a form to complete. Warnings and Error status should have helpful messaging added this way, and with links if useful.

On events that have been successfully completed, there is the option to display a time-stamp alongside the status.

Best practice for Timeline#

๐Ÿ’š Do's๐Ÿ’” Don'ts
Use a maximum of 10 stepsAdd too much detailed content
Consider if the title duplicates page titleUse illustrations or icons in additional content
Provide helpful messagingUse overly long event names
Use summary to set expectationsUse timestamp if it causes confusion with a date elsewhere on the page

Best practice for Individual Timeline Event#

๐Ÿ’š Do's๐Ÿ’” Don'ts
Use any one of default, icon or number decoration for all events in the timeline sequenceMix two different decoration types in events
Use ns-card to provide additional information for inprogress, actionrequired, warning and error eventsUse any icon type with names ending Solid or Outline
Always pick ns-icon type from the specification provided in below section


View example on Storybook

Component placement#

The ns-timeline component can only be used in the ns-panel component.

The ns-timeline-event component can only be used in the ns-timeline component.

Specification for Timeline#

showstepcountbooleanfalsetrue, falseSet true to show completed vs total event progress count below the timeline heading

Specification for Individual Timeline Event#

statusstringpendingpending, inprogress, actionrequired, warning, error, completed, cancelled
iconstringappliance, bill, boiler, calendar, clock, download, electricity, energy, gas, home, meter, protect, rewards, search, tag. Please see the documentation for ns-iconOptional icon to add to the event decoration
indexnumberOptional numbered index to add to the event decoration
updatedAtdateOptional ISO date only used along with completed status to record the event completed date & time.


  • Do you have insights or concerns to share? You can raise an issue via Github bugs.
  • See all the issues already raised via Github issues.

๐Ÿ’ฉ ๐ŸŽ‰ ๐Ÿฆ„ You can also contact the team on Slack on the #product-nucleus channel!

Related links#