ASP Digital Design System

A-Z

The a-z nav component allows visitors to quickly check if a list has: an entry/entries, beginning with a letter and scroll to that section.

Open this example in a new tab: a-z

<nav class="asp-a-z">
  <ul class="asp-a-z__list">
    <li class="asp-a-z__placeholder">
      a
    </li>
    <li class="asp-a-z__placeholder">
      b
    </li>
    <li>
      <a href="#a-z-c">c</a>
    </li>
    <li>
      <a href="#a-z-d">d</a>
    </li>
    <li class="asp-a-z__placeholder">
      e
    </li>
    <li class="asp-a-z__placeholder">
      f
    </li>
    <li class="asp-a-z__placeholder">
      g
    </li>
    <li class="asp-a-z__placeholder">
      h
    </li>
    <li class="asp-a-z__placeholder">
      i
    </li>
    <li class="asp-a-z__placeholder">
      j
    </li>
    <li class="asp-a-z__placeholder">
      k
    </li>
    <li class="asp-a-z__placeholder">
      l
    </li>
    <li class="asp-a-z__placeholder">
      m
    </li>
    <li class="asp-a-z__placeholder">
      n
    </li>
    <li class="asp-a-z__placeholder">
      o
    </li>
    <li>
      <a href="#a-z-p">p</a>
    </li>
    <li class="asp-a-z__placeholder">
      q
    </li>
    <li class="asp-a-z__placeholder">
      r
    </li>
    <li class="asp-a-z__placeholder">
      s
    </li>
    <li class="asp-a-z__placeholder">
      t
    </li>
    <li class="asp-a-z__placeholder">
      u
    </li>
    <li class="asp-a-z__placeholder">
      v
    </li>
    <li class="asp-a-z__placeholder">
      w
    </li>
    <li class="asp-a-z__placeholder">
      x
    </li>
    <li class="asp-a-z__placeholder">
      y
    </li>
    <li class="asp-a-z__placeholder">
      z
    </li>
  </ul>
</nav>
<div class="section" id="a-z-c">
  <h2>c</h2>
  <p>Chris, Content (html) about Chris</p>
  <p>Claire, Content (html) about Claire</p>
</div>
<div class="section" id="a-z-d">
  <h2>d</h2>
  <p>Dave, Content (html) about Dave</p>
</div>
<div class="section" id="a-z-p">
  <h2>p</h2>
  <p>Pete, Content (text) about Pete</p>
</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
content array or false (boolean) The content between the lists. If false (boolean), the following parameters will be ignored. See content.
rows object Required. Object of all items within the A-Z component. See rows.

Options for content

Name Type Description
html string Required. HTML for the content between the lists. If 'html' is provided, the 'text' parameter will be ignored.
text string Required. Text for the content between the lists. If 'html' is provided, the 'text' parameter will be ignored.

Options for rows

Name Type Description
title string Required. The part of the A-Z item which first letter is used to create the indexing of the A-Z component.
content string Required. Other data associated with the A-Z item. See content.

Options for content

Name Type Description
html string Required. HTML for the data associated with the A-Z item. If 'html' is provided, the 'text' parameter will be ignored.
text string Required. Text for the data associated with the A-Z item. If 'html' is provided, the 'text' parameter will be ignored. 
{% from "a-z/macro.njk" import aspAZ %}


{{ aspAZ({
  rows: [
    {
      title: "Dave",
      content: {
        html: '<p>Dave, Content (html) about Dave</p>'  
      }
    },
    {
      title: "Chris",
      content: {
        html: '<p>Chris, Content (html) about Chris</p>'  
      }
    },
    {
      title: "Claire",
      content: {
        html: '<p>Claire, Content (html) about Claire</p>'  
      }
    },
    {
      title: "Pete",
      content: {
        text: "Pete, Content (text) about Pete"
      }
    }
  ]
}) }}

When to use this component

Use the a-z nav component as an on-page sub navigation where large lists of entries organised alphabetically are displayed.

When not to use this component

Do not use the a-z nav component with small lists or lists that contain entries starting with a small selection of characters or lists that are not ordered alphabetically.

How it works

Position the a-z nav component immediately before the list of entries, which may be created dynamically.

Wrap all entries beginning with the same letter in an element, ensuring that the element has a corresponding id attribute. If no entries are found for that letter, a placeholder should be substituted for a link within the a-z nav 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 11 September 2024