ASP Digital Design System

Steps

The ‘Steps’ element helps triage users through a number of steps. This helps them to follow the actions they need to complete, and also helps us to manage demand on services.

Users can self-service the content but using the clearly labelled steps.

This component is used sparingly on the website.

The example below shows the list above the steps component.

Open this example in a new tab: steps

<ul class="asp-steps__links">
  <li class="asp-steps__item">
    <a class="asp-js-toggle-button" href="#step1" data-toggle-element=".step1" data-toggle-steps="true"><span class="sr-only">Step 1:</span> Title of step 1</a>
  </li>
  <li class="asp-steps__item">
    <a class="asp-js-toggle-button" href="#step2" data-toggle-element=".step2" data-toggle-steps="true"><span class="sr-only">Step 2:</span> Title of step 2</a>
  </li>
  <li class="asp-steps__item">
    <a class="asp-js-toggle-button" href="#step3" data-toggle-element=".step3" data-toggle-steps="true"><span class="sr-only">Step 3:</span> Title of step 3</a>
  </li>
</ul>
<ol class="asp-steps">
  <li class="asp-step" id="step1">
    <h2 class="asp-step__heading">
      <span class="asp-step__number">
        <span class="sr-only">Step</span>
        1
        <span class="sr-only">:</span>
      </span>
      <noscript>
        <span class="asp-step__title">Title of step 1</span>
      </noscript>
      <button class="asp-step__button asp-button--toggleable asp-js-toggle-button" type="button" data-toggle-element=".step1" aria-expanded="false" style="display:none">
        <span class="asp-step__title">Title of step 1</span>
        <span aria-hidden="true">
          <span class="asp-step__showhide asp-button--toggleable__text-hide">Hide </span>
          <span class="asp-step__showhide asp-button--toggleable__text-show">Show </span>
        </span>
      </button>
    </h2>
    <div class="asp-step__content step1">
      <p>Step 1 content (html). expanded: true</p>
    </div>
  </li>
  <li class="asp-step" id="step2">
    <h2 class="asp-step__heading">
      <span class="asp-step__number">
        <span class="sr-only">Step</span>
        2
        <span class="sr-only">:</span>
      </span>
      <noscript>
        <span class="asp-step__title">Title of step 2</span>
      </noscript>
      <button class="asp-step__button asp-button--toggleable asp-js-toggle-button" type="button" data-toggle-element=".step2" aria-expanded="false" style="display:none">
        <span class="asp-step__title">Title of step 2</span>
        <span aria-hidden="true">
          <span class="asp-step__showhide asp-button--toggleable__text-hide">Hide </span>
          <span class="asp-step__showhide asp-button--toggleable__text-show">Show </span>
        </span>
      </button>
    </h2>
    <div class="asp-step__content step2">
      <p>Step 2 content (html) with a <a href="#">link</a>.</p>
                <p>With additional line.</p>
    </div>
  </li>
  <li class="asp-step" id="step3">
    <h2 class="asp-step__heading">
      <span class="asp-step__number">
        <span class="sr-only">Step</span>
        3
        <span class="sr-only">:</span>
      </span>
      <noscript>
        <span class="asp-step__title">Title of step 3</span>
      </noscript>
      <button class="asp-step__button asp-button--toggleable asp-js-toggle-button" type="button" data-toggle-element=".step3" aria-expanded="false" style="display:none">
        <span class="asp-step__title">Title of step 3</span>
        <span aria-hidden="true">
          <span class="asp-step__showhide asp-button--toggleable__text-hide">Hide </span>
          <span class="asp-step__showhide asp-button--toggleable__text-show">Show </span>
        </span>
      </button>
    </h2>
    <div class="asp-step__content step3">
      <p>Step 3 content (text).</p>
    </div>
  </li>
</ol>
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
uniqueID string or false (boolean) A unique ID that prepends to ids within the steps component to ensure step ids are unique. Default values are alphanumeric characters with hyphens and/or underscores [a-zA-Z0-9-_], false (boolean) or null.
showList boolean Default values are false (boolean), true (boolean) and null.
openSteps string or false (boolean) Default values are 'first', 'all', false (boolean) and null. 'first' will show only the first step as open, 'all' will show all steps as open.
rows object Required. Object of each step. See rows.

Options for rows

Name Type Description
title string Required. The title for the step.
content array Required. The step content. See content.

Options for content

Name Type Description
html string Required. HTML for the step content. If 'html' is provided, the 'text' parameter will be ignored.
text string Required. Text for the step content. If 'html' is provided, the 'text' parameter will be ignored. 
{% from "steps/macro.njk" import aspSteps %}


{{ aspSteps({
  showList: true,
  rows: [
    {
      title: "Title of step 1",
      expanded: true,
      content: {
        html: '<p>Step 1 content (html). expanded: true</p>'  
      }
    },
    {
      title: "Title of step 2",
      content: {
        html: '<p>Step 2 content (html) with a <a href="#">link</a>.</p>
          <p>With additional line.</p>'  
      }
    },
    {
      title: "Title of step 3",
      content: {
        text: 'Step 3 content (text).'
      }
    }
  ]
}) }}
Twig 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
uniqueID string or false (boolean) A unique ID that prepends to ids within the steps component to ensure step ids are unique. Default values are alphanumeric characters with hyphens and/or underscores [a-zA-Z0-9-_], false (boolean) or null.
showList boolean Default values are false (boolean), true (boolean) and null.
openSteps string or false (boolean) Default values are 'first', 'all', false (boolean) and null. 'first' will show only the first step as open, 'all' will show all steps as open.
rows object Required. Object of each step. See rows.

Options for rows

Name Type Description
title string Required. The title for the step.
content array Required. The step content. See content.

Options for content

Name Type Description
html string Required. HTML for the step content. If 'html' is provided, the 'text' parameter will be ignored.
text string Required. Text for the step content. If 'html' is provided, the 'text' parameter will be ignored. 
{% from "steps/macro.njk" import aspSteps %}


{{ aspSteps({
  showList: true,
  rows: [
    {
      title: "Title of step 1",
      expanded: true,
      content: {
        html: '<p>Step 1 content (html). expanded: true</p>'  
      }
    },
    {
      title: "Title of step 2",
      content: {
        html: '<p>Step 2 content (html) with a <a href="#">link</a>.</p>
          <p>With additional line.</p>'  
      }
    },
    {
      title: "Title of step 3",
      content: {
        text: 'Step 3 content (text).'
      }
    }
  ]
}) }}

Steps with open steps

The example below shows the steps component with the first step open. Note the uniqueID parameter.

Open this example in a new tab: steps

<ol class="asp-steps">
  <li class="asp-step" id="example-2step1">
    <h2 class="asp-step__heading">
      <span class="asp-step__number">
        <span class="sr-only">Step</span>
        1
        <span class="sr-only">:</span>
      </span>
      <noscript>
        <span class="asp-step__title">Title of step 1</span>
      </noscript>
      <button class="asp-step__button asp-button--toggleable asp-js-toggle-button" type="button" data-toggle-element=".example-2step1" aria-expanded="true" style="display:none">
        <span class="asp-step__title">Title of step 1</span>
        <span aria-hidden="true">
          <span class="asp-step__showhide asp-button--toggleable__text-hide">Hide </span>
          <span class="asp-step__showhide asp-button--toggleable__text-show">Show </span>
        </span>
      </button>
    </h2>
    <div class="asp-step__content example-2step1">
      <p>Step 1 content (html). expanded: true</p>
    </div>
  </li>
  <li class="asp-step" id="example-2step2">
    <h2 class="asp-step__heading">
      <span class="asp-step__number">
        <span class="sr-only">Step</span>
        2
        <span class="sr-only">:</span>
      </span>
      <noscript>
        <span class="asp-step__title">Title of step 2</span>
      </noscript>
      <button class="asp-step__button asp-button--toggleable asp-js-toggle-button" type="button" data-toggle-element=".example-2step2" aria-expanded="false" style="display:none">
        <span class="asp-step__title">Title of step 2</span>
        <span aria-hidden="true">
          <span class="asp-step__showhide asp-button--toggleable__text-hide">Hide </span>
          <span class="asp-step__showhide asp-button--toggleable__text-show">Show </span>
        </span>
      </button>
    </h2>
    <div class="asp-step__content example-2step2">
      <p>Step 2 content (html) with a <a href="#">link</a>.</p>
                <p>With additional line.</p>
    </div>
  </li>
  <li class="asp-step" id="example-2step3">
    <h2 class="asp-step__heading">
      <span class="asp-step__number">
        <span class="sr-only">Step</span>
        3
        <span class="sr-only">:</span>
      </span>
      <noscript>
        <span class="asp-step__title">Title of step 3</span>
      </noscript>
      <button class="asp-step__button asp-button--toggleable asp-js-toggle-button" type="button" data-toggle-element=".example-2step3" aria-expanded="false" style="display:none">
        <span class="asp-step__title">Title of step 3</span>
        <span aria-hidden="true">
          <span class="asp-step__showhide asp-button--toggleable__text-hide">Hide </span>
          <span class="asp-step__showhide asp-button--toggleable__text-show">Show </span>
        </span>
      </button>
    </h2>
    <div class="asp-step__content example-2step3">
      <p>Step 3 content (text).</p>
    </div>
  </li>
</ol>
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
uniqueID string or false (boolean) A unique ID that prepends to ids within the steps component to ensure step ids are unique. Default values are alphanumeric characters with hyphens and/or underscores [a-zA-Z0-9-_], false (boolean) or null.
showList boolean Default values are false (boolean), true (boolean) and null.
openSteps string or false (boolean) Default values are 'first', 'all', false (boolean) and null. 'first' will show only the first step as open, 'all' will show all steps as open.
rows object Required. Object of each step. See rows.

Options for rows

Name Type Description
title string Required. The title for the step.
content array Required. The step content. See content.

Options for content

Name Type Description
html string Required. HTML for the step content. If 'html' is provided, the 'text' parameter will be ignored.
text string Required. Text for the step content. If 'html' is provided, the 'text' parameter will be ignored. 
{% from "steps/macro.njk" import aspSteps %}


{{ aspSteps({
  uniqueID: "example-2",
  openSteps: "first",
  rows: [
    {
      title: "Title of step 1",
      expanded: true,
      content: {
        html: '<p>Step 1 content (html). expanded: true</p>'  
      }
    },
    {
      title: "Title of step 2",
      content: {
        html: '<p>Step 2 content (html) with a <a href="#">link</a>.</p>
          <p>With additional line.</p>'  
      }
    },
    {
      title: "Title of step 3",
      content: {
        text: 'Step 3 content (text).'
      }
    }
  ]
}) }}
Twig 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
uniqueID string or false (boolean) A unique ID that prepends to ids within the steps component to ensure step ids are unique. Default values are alphanumeric characters with hyphens and/or underscores [a-zA-Z0-9-_], false (boolean) or null.
showList boolean Default values are false (boolean), true (boolean) and null.
openSteps string or false (boolean) Default values are 'first', 'all', false (boolean) and null. 'first' will show only the first step as open, 'all' will show all steps as open.
rows object Required. Object of each step. See rows.

Options for rows

Name Type Description
title string Required. The title for the step.
content array Required. The step content. See content.

Options for content

Name Type Description
html string Required. HTML for the step content. If 'html' is provided, the 'text' parameter will be ignored.
text string Required. Text for the step content. If 'html' is provided, the 'text' parameter will be ignored. 
{% from "steps/macro.njk" import aspSteps %}


{{ aspSteps({
  uniqueID: "example-2",
  openSteps: "first",
  rows: [
    {
      title: "Title of step 1",
      expanded: true,
      content: {
        html: '<p>Step 1 content (html). expanded: true</p>'  
      }
    },
    {
      title: "Title of step 2",
      content: {
        html: '<p>Step 2 content (html) with a <a href="#">link</a>.</p>
          <p>With additional line.</p>'  
      }
    },
    {
      title: "Title of step 3",
      content: {
        text: 'Step 3 content (text).'
      }
    }
  ]
}) }}

The example below shows the steps component with all steps open. Note the uniqueID parameter.

Open this example in a new tab: steps

<ol class="asp-steps">
  <li class="asp-step" id="example-3step1">
    <h2 class="asp-step__heading">
      <span class="asp-step__number">
        <span class="sr-only">Step</span>
        1
        <span class="sr-only">:</span>
      </span>
      <noscript>
        <span class="asp-step__title">Title of step 1</span>
      </noscript>
      <button class="asp-step__button asp-button--toggleable asp-js-toggle-button" type="button" data-toggle-element=".example-3step1" aria-expanded="true" style="display:none">
        <span class="asp-step__title">Title of step 1</span>
        <span aria-hidden="true">
          <span class="asp-step__showhide asp-button--toggleable__text-hide">Hide </span>
          <span class="asp-step__showhide asp-button--toggleable__text-show">Show </span>
        </span>
      </button>
    </h2>
    <div class="asp-step__content example-3step1">
      <p>Step 1 content (html). expanded: true</p>
    </div>
  </li>
  <li class="asp-step" id="example-3step2">
    <h2 class="asp-step__heading">
      <span class="asp-step__number">
        <span class="sr-only">Step</span>
        2
        <span class="sr-only">:</span>
      </span>
      <noscript>
        <span class="asp-step__title">Title of step 2</span>
      </noscript>
      <button class="asp-step__button asp-button--toggleable asp-js-toggle-button" type="button" data-toggle-element=".example-3step2" aria-expanded="true" style="display:none">
        <span class="asp-step__title">Title of step 2</span>
        <span aria-hidden="true">
          <span class="asp-step__showhide asp-button--toggleable__text-hide">Hide </span>
          <span class="asp-step__showhide asp-button--toggleable__text-show">Show </span>
        </span>
      </button>
    </h2>
    <div class="asp-step__content example-3step2">
      <p>Step 2 content (html) with a <a href="#">link</a>.</p>
                <p>With additional line.</p>
    </div>
  </li>
  <li class="asp-step" id="example-3step3">
    <h2 class="asp-step__heading">
      <span class="asp-step__number">
        <span class="sr-only">Step</span>
        3
        <span class="sr-only">:</span>
      </span>
      <noscript>
        <span class="asp-step__title">Title of step 3</span>
      </noscript>
      <button class="asp-step__button asp-button--toggleable asp-js-toggle-button" type="button" data-toggle-element=".example-3step3" aria-expanded="true" style="display:none">
        <span class="asp-step__title">Title of step 3</span>
        <span aria-hidden="true">
          <span class="asp-step__showhide asp-button--toggleable__text-hide">Hide </span>
          <span class="asp-step__showhide asp-button--toggleable__text-show">Show </span>
        </span>
      </button>
    </h2>
    <div class="asp-step__content example-3step3">
      <p>Step 3 content (text).</p>
    </div>
  </li>
</ol>
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
uniqueID string or false (boolean) A unique ID that prepends to ids within the steps component to ensure step ids are unique. Default values are alphanumeric characters with hyphens and/or underscores [a-zA-Z0-9-_], false (boolean) or null.
showList boolean Default values are false (boolean), true (boolean) and null.
openSteps string or false (boolean) Default values are 'first', 'all', false (boolean) and null. 'first' will show only the first step as open, 'all' will show all steps as open.
rows object Required. Object of each step. See rows.

Options for rows

Name Type Description
title string Required. The title for the step.
content array Required. The step content. See content.

Options for content

Name Type Description
html string Required. HTML for the step content. If 'html' is provided, the 'text' parameter will be ignored.
text string Required. Text for the step content. If 'html' is provided, the 'text' parameter will be ignored. 
{% from "steps/macro.njk" import aspSteps %}


{{ aspSteps({
  uniqueID: "example-3",
  openSteps: "all",
  rows: [
    {
      title: "Title of step 1",
      expanded: true,
      content: {
        html: '<p>Step 1 content (html). expanded: true</p>'  
      }
    },
    {
      title: "Title of step 2",
      content: {
        html: '<p>Step 2 content (html) with a <a href="#">link</a>.</p>
          <p>With additional line.</p>'  
      }
    },
    {
      title: "Title of step 3",
      content: {
        text: 'Step 3 content (text).'
      }
    }
  ]
}) }}
Twig 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
uniqueID string or false (boolean) A unique ID that prepends to ids within the steps component to ensure step ids are unique. Default values are alphanumeric characters with hyphens and/or underscores [a-zA-Z0-9-_], false (boolean) or null.
showList boolean Default values are false (boolean), true (boolean) and null.
openSteps string or false (boolean) Default values are 'first', 'all', false (boolean) and null. 'first' will show only the first step as open, 'all' will show all steps as open.
rows object Required. Object of each step. See rows.

Options for rows

Name Type Description
title string Required. The title for the step.
content array Required. The step content. See content.

Options for content

Name Type Description
html string Required. HTML for the step content. If 'html' is provided, the 'text' parameter will be ignored.
text string Required. Text for the step content. If 'html' is provided, the 'text' parameter will be ignored. 
{% from "steps/macro.njk" import aspSteps %}


{{ aspSteps({
  uniqueID: "example-3",
  openSteps: "all",
  rows: [
    {
      title: "Title of step 1",
      expanded: true,
      content: {
        html: '<p>Step 1 content (html). expanded: true</p>'  
      }
    },
    {
      title: "Title of step 2",
      content: {
        html: '<p>Step 2 content (html) with a <a href="#">link</a>.</p>
          <p>With additional line.</p>'  
      }
    },
    {
      title: "Title of step 3",
      content: {
        text: 'Step 3 content (text).'
      }
    }
  ]
}) }}

Alias

What was known as a steps component on the ‘frontend’ is now a progress component.

Status of development

The below criteria all need to be met for a component to be considered as fully developed for use within the ASP Digital Design System.

Development criteria Status
WCAG 2.2 compliant Not started
WCAG 2.1 compliant Completed
HTML / Nunjucks version Completed
Figma version Not started
M365 versions Not started
Documentation In progress

Published 3 May 2024
Last updated 5 November 2024