Style Typography

Overview

Text is the primary way users digest information and complete tasks, so it’s important to use good typographic principles to establish a clear visual hierarchy and to maximise legibility.

Font

The primary font used in ONS digital products is Open Sans (opens in a new tab) . Stylistic set 1 is used because it includes the more accessible opentail lowercase ‘g’, and serifed capital ‘I’.

Open Sans, with its broad range of weights and extensive unicode support was chosen to provide a good balance between legibility, personality and readability. As the majority of our User Interface (UI) is text-based, we use weight and size to denote hierarchy and separation between content. Open Sans’ letterforms also provide a good level of contrast which aid readability on poorer quality displays and for users with visual impairment.

Font family: “Open Sans”, “Helvetica Neue”, Helvetica, Arial, sans-serif

Font weights

Bold: 700
Regular: 400

Type scale

Using the type scale classes on text elements, the type is sized appropriately above and below the medium breakpoint.

Headings

Heading defaults are as follows:

Breakpoint headings

Font sizes can be triggered at certain breakpoints. Just suffix any font size class with @{breakpoint}, for example, ons-u-fs-m@l

Paragraphs

The base font size for paragraphs is 18px.

Links

Links are blue and underlined by default. If your link is at the end of a sentence or paragraph, make sure that the linked text does not include the full stop.

Links that open in a new tab

Only open a link in a new tab when necessary, such as when:

linking to a document (PDF, Word file) to prevent users from losing their place
directing users to an external service they may need to reference while completing a task
ensuring users do not lose entered data when navigating away.

Include (opens in a new tab) in the visible link text as screen readers may not announce an icon. Avoid opening multiple new tabs unnecessarily.

External Links

Links to external websites using the onsExternalLink macro will have the attributes target="_blank" to open websites in a new tab, and rel="noopener" to guard against a security vulnerability which can be exploited by malicious websites.

Use the external link icon only for links leading outside ons.gov.uk

This includes:

official statistics hosted on other government websites
third-party research or external datasets
references to external policies, legislation, or academic sources.

Use the external link icon with clear text indicating that the link goes to another site.

If a link both opens in a new tab and leads to an external site, make this clear in the link text so that users can clearly distinguish between external links and those opening in a new tab, ensuring an accessible and predictable experience.

Example External Link contents

Nunjucksfor Example External Link
Nunjucks macro optionsfor Example External Link
HTMLfor Example External Link

Nunjucks

{% from "components/external-link/_macro.njk" import onsExternalLink %}

<p>
    This is a paragraph of text with a
    {{
        onsExternalLink({
            "url": "#0",
            "text": "link to an external website"
        })
    }}
</p>

Nunjucks macro options

Name	Type	Required	Description
url	string	true	The URL for the `href` attribute of the external link
text	string	true	Text for the external link
classes	string	false	Classes to apply to the link
newWindowDescription	string	false	Use to set context after the `linkText` label for screen readers. Defaults to “opens in a new tab”

HTML

<p> This is a paragraph of text with a <a href="#0" class="ons-external-link" target="_blank" rel="noopener">
    <span class="ons-external-link__text">link to an external website</span><span
      class="ons-external-link__icon">&nbsp;<svg class="ons-icon" viewBox="0 0 12 12" xmlns="http://www.w3.org/2000/svg"
        focusable="false" aria-hidden="true" role="img" title="ons-icon-external-link">
        <path
          d="M13.5,9H13a.5.5,0,0,0-.5.5v3h-9v-9h3A.5.5,0,0,0,7,3V2.5A.5.5,0,0,0,6.5,2h-4a.5.5,0,0,0-.5.5v11a.5.5,0,0,0,.5.5h11a.5.5,0,0,0,.5-.5v-4A.5.5,0,0,0,13.5,9Z"
          transform="translate(-2 -1.99)" />
        <path
          d="M8.83,7.88a.51.51,0,0,0,.71,0l2.31-2.32,1.28,1.28A.51.51,0,0,0,14,6.49v-4a.52.52,0,0,0-.5-.5h-4A.51.51,0,0,0,9,2.52a.58.58,0,0,0,.14.33l1.28,1.28L8.12,6.46a.51.51,0,0,0,0,.71Z"
          transform="translate(-2 -1.99)" />
      </svg></span><span class="ons-external-link__new-window-description ons-u-vh">(opens in a new tab)</span></a>
</p>

Lists

Use lists to break up blocks of text into concise, manageable chunks to make it easier to read.

Bulleted list (default)

Bulleted lists should be introduced with a lead-in line, ending in a colon.

Each item in the list should start with a lowercase letter and should not end with a full stop.

Example Bulleted List contents

Nunjucksfor Example Bulleted List
Nunjucks macro optionsfor Example Bulleted List
HTMLfor Example Bulleted List

Nunjucks

{% from "components/list/_macro.njk" import onsList %}
<p>You will need to show <strong>one</strong> of the following forms of ID:</p>
{{
    onsList({
        "itemsList": [
            {
                "text": 'birth certificate'
            },
            {
                "text": 'national insurance number'
            },
            {
                "text": 'passport'
            }
        ]
    })
}}

Nunjucks macro options

Name	Type	Required	Description
element	string	false	The wrapping element for the list. If nothing is defined it will default to `<ul>`
id	string	false	The HTML `id` for the wrapping element
classes	string	false	Classes to be added to the wrapping element
itemsList	`Array<ListItem>`	true	Settings for each list item
variants	array or string	false	An array of values or single value (string) to adjust the component using available variants: “bare”, “dashed”, “inline”, "summary", and “languages”
iconPosition	string	false	Sets position of icon to “before” or “after” each list item
iconType	string	false	Adds an icon to all the list items when set to the name of one of the available icons. Requires `iconPosition` to be set.
iconSize	string	false	Icon size can be set to match the size of the list item text as detailed in the typography type scale.
attributes	object	false	HTML attributes (for example, data attributes) to add to wrapping element

ListItem
Name	Type	Required	Description
listClasses	string	false	Classes to be added to the list item
text	string	true	The text for the list item
title	string	false	The text for the list item - used for Craft CMS
navigationTitle	string	false	The text for the list item - used for Craft CMS
url	string	false	Wraps the list item text in a link with the set `href`
classes	string	false	Classes to be added to the list item link
target	string	false	Sets the HTML `target` attribute for the list item when `url` is set
screenreaderMessage	string	false	Sets a message to be read out by screen readers when `target` is set to “_blank” to open a new tab. Defaults to “opens in a new tab”.
external	boolean	false	Sets the list item as an external link
prefix	string	false	Will prefix the list item with the parameter’s value
suffix	string	false	Will suffix the list item with the parameter’s value
current	boolean	false	Set to “true” to indicate the current page in a list of content navigational links
iconType	string	false	Adds an icon to the individual list item when set to the name of one of the available icons
attributes	object	false	HTML attributes (for example, data attributes) to add to list item
itemsList	`Array<ListItem>`	false	Settings for each list item

HTML

<p>You will need to show <strong>one</strong> of the following forms of ID:</p>
<ul class="ons-list">
  <li class="ons-list__item"> birth certificate </li>
  <li class="ons-list__item"> national insurance number </li>
  <li class="ons-list__item"> passport </li>
</ul>

Numbered list

Numbered lists should be displayed in place of bulleted lists when the order of items is relevant.

Each list item should be a complete sentence, therefore start with an uppercase letter, and end with a full stop.

You do not need to introduce a numbered list with a lead-in line.

To use a numbered list when using the list macro you need to not be using a bare list and set the element parameter to “ol”.

If there is only one item in the list when using the list macro it will render the item in <p> tags and not a list with no list styling added.

Example Numbered List contents

Nunjucksfor Example Numbered List
Nunjucks macro optionsfor Example Numbered List
HTMLfor Example Numbered List

Nunjucks

{% from "components/list/_macro.njk" import onsList %}
{{
    onsList({
        "element": 'ol',
        "itemsList": [
            {
                "text": 'Introduction'
            },
            {
                "text": 'Questionnaire'
            },
            {
                "text": 'Summary'
            }
        ]
    })
}}

Nunjucks macro options

Name	Type	Required	Description
element	string	false	The wrapping element for the list. If nothing is defined it will default to `<ul>`
id	string	false	The HTML `id` for the wrapping element
classes	string	false	Classes to be added to the wrapping element
itemsList	`Array<ListItem>`	true	Settings for each list item
variants	array or string	false	An array of values or single value (string) to adjust the component using available variants: “bare”, “dashed”, “inline”, "summary", and “languages”
iconPosition	string	false	Sets position of icon to “before” or “after” each list item
iconType	string	false	Adds an icon to all the list items when set to the name of one of the available icons. Requires `iconPosition` to be set.
iconSize	string	false	Icon size can be set to match the size of the list item text as detailed in the typography type scale.
attributes	object	false	HTML attributes (for example, data attributes) to add to wrapping element

ListItem
Name	Type	Required	Description
listClasses	string	false	Classes to be added to the list item
text	string	true	The text for the list item
title	string	false	The text for the list item - used for Craft CMS
navigationTitle	string	false	The text for the list item - used for Craft CMS
url	string	false	Wraps the list item text in a link with the set `href`
classes	string	false	Classes to be added to the list item link
target	string	false	Sets the HTML `target` attribute for the list item when `url` is set
screenreaderMessage	string	false	Sets a message to be read out by screen readers when `target` is set to “_blank” to open a new tab. Defaults to “opens in a new tab”.
external	boolean	false	Sets the list item as an external link
prefix	string	false	Will prefix the list item with the parameter’s value
suffix	string	false	Will suffix the list item with the parameter’s value
current	boolean	false	Set to “true” to indicate the current page in a list of content navigational links
iconType	string	false	Adds an icon to the individual list item when set to the name of one of the available icons
attributes	object	false	HTML attributes (for example, data attributes) to add to list item
itemsList	`Array<ListItem>`	false	Settings for each list item

HTML

<ol class="ons-list">
  <li class="ons-list__item"> Introduction </li>
  <li class="ons-list__item"> Questionnaire </li>
  <li class="ons-list__item"> Summary </li>
</ol>

Bare list

Bare lists should be used to display a list of navigational links, for example, a group of related pages displayed in the footer.

Example Bare List contents

Nunjucksfor Example Bare List
Nunjucks macro optionsfor Example Bare List
HTMLfor Example Bare List

Nunjucks

{% from "components/list/_macro.njk" import onsList %}
{{
    onsList({
        "variants": 'bare',
        "itemsList": [
            {
                "url": '#0',
                "text": 'Who we are'
            },
            {
                "url": '#0',
                "text": 'What we do'
            },
            {
                "url": 'https://goo.gl/maps/ULnVRd16zfFLZWdt7',
                "text": 'Where to find us',
                "external": true
            }
        ]
    })
}}

Nunjucks macro options

Name	Type	Required	Description
element	string	false	The wrapping element for the list. If nothing is defined it will default to `<ul>`
id	string	false	The HTML `id` for the wrapping element
classes	string	false	Classes to be added to the wrapping element
itemsList	`Array<ListItem>`	true	Settings for each list item
variants	array or string	false	An array of values or single value (string) to adjust the component using available variants: “bare”, “dashed”, “inline”, "summary", and “languages”
iconPosition	string	false	Sets position of icon to “before” or “after” each list item
iconType	string	false	Adds an icon to all the list items when set to the name of one of the available icons. Requires `iconPosition` to be set.
iconSize	string	false	Icon size can be set to match the size of the list item text as detailed in the typography type scale.
attributes	object	false	HTML attributes (for example, data attributes) to add to wrapping element

ListItem
Name	Type	Required	Description
listClasses	string	false	Classes to be added to the list item
text	string	true	The text for the list item
title	string	false	The text for the list item - used for Craft CMS
navigationTitle	string	false	The text for the list item - used for Craft CMS
url	string	false	Wraps the list item text in a link with the set `href`
classes	string	false	Classes to be added to the list item link
target	string	false	Sets the HTML `target` attribute for the list item when `url` is set
screenreaderMessage	string	false	Sets a message to be read out by screen readers when `target` is set to “_blank” to open a new tab. Defaults to “opens in a new tab”.
external	boolean	false	Sets the list item as an external link
prefix	string	false	Will prefix the list item with the parameter’s value
suffix	string	false	Will suffix the list item with the parameter’s value
current	boolean	false	Set to “true” to indicate the current page in a list of content navigational links
iconType	string	false	Adds an icon to the individual list item when set to the name of one of the available icons
attributes	object	false	HTML attributes (for example, data attributes) to add to list item
itemsList	`Array<ListItem>`	false	Settings for each list item

HTML

<ul class="ons-list ons-list--bare">
  <li class="ons-list__item">
    <a href="#0" class="ons-list__link">Who we are</a>
  </li>
  <li class="ons-list__item">
    <a href="#0" class="ons-list__link">What we do</a>
  </li>
  <li class="ons-list__item">
    <a href="https://goo.gl/maps/ULnVRd16zfFLZWdt7" class="ons-external-link" target="_blank" rel="noopener">
      <span class="ons-external-link__text">Where to find us</span><span class="ons-external-link__icon">&nbsp;<svg
          class="ons-icon" viewBox="0 0 12 12" xmlns="http://www.w3.org/2000/svg" focusable="false" aria-hidden="true"
          role="img" title="ons-icon-external-link">
          <path
            d="M13.5,9H13a.5.5,0,0,0-.5.5v3h-9v-9h3A.5.5,0,0,0,7,3V2.5A.5.5,0,0,0,6.5,2h-4a.5.5,0,0,0-.5.5v11a.5.5,0,0,0,.5.5h11a.5.5,0,0,0,.5-.5v-4A.5.5,0,0,0,13.5,9Z"
            transform="translate(-2 -1.99)" />
          <path
            d="M8.83,7.88a.51.51,0,0,0,.71,0l2.31-2.32,1.28,1.28A.51.51,0,0,0,14,6.49v-4a.52.52,0,0,0-.5-.5h-4A.51.51,0,0,0,9,2.52a.58.58,0,0,0,.14.33l1.28,1.28L8.12,6.46a.51.51,0,0,0,0,.71Z"
            transform="translate(-2 -1.99)" />
        </svg></span><span class="ons-external-link__new-window-description ons-u-vh">(opens in a new tab)</span></a>
  </li>
</ul>

Dashed list

Dashed lists should be used to display a list of content navigational links.

Example Dashed List contents

Nunjucksfor Example Dashed List
Nunjucks macro optionsfor Example Dashed List
HTMLfor Example Dashed List

Nunjucks

{% from "components/list/_macro.njk" import onsList %}
{{
    onsList({
        "variants": 'dashed',
        "itemsList": [
            {
                "text": 'Overview',
                "current": true
            },
            {
                "url": '#0',
                "text": 'About Census 2021'
            },
            {
                "url": '#0',
                "text": 'Why should I take part in the census?'
            }
        ]
    })
}}

Nunjucks macro options

Name	Type	Required	Description
element	string	false	The wrapping element for the list. If nothing is defined it will default to `<ul>`
id	string	false	The HTML `id` for the wrapping element
classes	string	false	Classes to be added to the wrapping element
itemsList	`Array<ListItem>`	true	Settings for each list item
variants	array or string	false	An array of values or single value (string) to adjust the component using available variants: “bare”, “dashed”, “inline”, "summary", and “languages”
iconPosition	string	false	Sets position of icon to “before” or “after” each list item
iconType	string	false	Adds an icon to all the list items when set to the name of one of the available icons. Requires `iconPosition` to be set.
iconSize	string	false	Icon size can be set to match the size of the list item text as detailed in the typography type scale.
attributes	object	false	HTML attributes (for example, data attributes) to add to wrapping element

ListItem
Name	Type	Required	Description
listClasses	string	false	Classes to be added to the list item
text	string	true	The text for the list item
title	string	false	The text for the list item - used for Craft CMS
navigationTitle	string	false	The text for the list item - used for Craft CMS
url	string	false	Wraps the list item text in a link with the set `href`
classes	string	false	Classes to be added to the list item link
target	string	false	Sets the HTML `target` attribute for the list item when `url` is set
screenreaderMessage	string	false	Sets a message to be read out by screen readers when `target` is set to “_blank” to open a new tab. Defaults to “opens in a new tab”.
external	boolean	false	Sets the list item as an external link
prefix	string	false	Will prefix the list item with the parameter’s value
suffix	string	false	Will suffix the list item with the parameter’s value
current	boolean	false	Set to “true” to indicate the current page in a list of content navigational links
iconType	string	false	Adds an icon to the individual list item when set to the name of one of the available icons
attributes	object	false	HTML attributes (for example, data attributes) to add to list item
itemsList	`Array<ListItem>`	false	Settings for each list item

HTML

<ul class="ons-list ons-list--dashed">
  <li class="ons-list__item" aria-current="true"> Overview </li>
  <li class="ons-list__item">
    <a href="#0" class="ons-list__link">About Census 2021</a>
  </li>
  <li class="ons-list__item">
    <a href="#0" class="ons-list__link">Why should I take part in the census?</a>
  </li>
</ul>

Prefixed list

The prefix list allows each list item to contain a string as a prefix to the item. The prefixed string uses our monospaced font to ensure spacing and alignment is correct.

Example Prefixed List contents

Nunjucksfor Example Prefixed List
Nunjucks macro optionsfor Example Prefixed List
HTMLfor Example Prefixed List

Nunjucks

{% from "components/list/_macro.njk" import onsList %}
{{
    onsList({
        "itemsList": [
            {
                "text": 'birth certificate',
                "prefix": 'H1'
            },
            {
                "text": 'national insurance number',
                "prefix": 'H2'
            },
            {
                "text": 'passport',
                "prefix": 'H3'
            }
        ]
    })
}}

Nunjucks macro options

Name	Type	Required	Description
element	string	false	The wrapping element for the list. If nothing is defined it will default to `<ul>`
id	string	false	The HTML `id` for the wrapping element
classes	string	false	Classes to be added to the wrapping element
itemsList	`Array<ListItem>`	true	Settings for each list item
variants	array or string	false	An array of values or single value (string) to adjust the component using available variants: “bare”, “dashed”, “inline”, "summary", and “languages”
iconPosition	string	false	Sets position of icon to “before” or “after” each list item
iconType	string	false	Adds an icon to all the list items when set to the name of one of the available icons. Requires `iconPosition` to be set.
iconSize	string	false	Icon size can be set to match the size of the list item text as detailed in the typography type scale.
attributes	object	false	HTML attributes (for example, data attributes) to add to wrapping element

ListItem
Name	Type	Required	Description
listClasses	string	false	Classes to be added to the list item
text	string	true	The text for the list item
title	string	false	The text for the list item - used for Craft CMS
navigationTitle	string	false	The text for the list item - used for Craft CMS
url	string	false	Wraps the list item text in a link with the set `href`
classes	string	false	Classes to be added to the list item link
target	string	false	Sets the HTML `target` attribute for the list item when `url` is set
screenreaderMessage	string	false	Sets a message to be read out by screen readers when `target` is set to “_blank” to open a new tab. Defaults to “opens in a new tab”.
external	boolean	false	Sets the list item as an external link
prefix	string	false	Will prefix the list item with the parameter’s value
suffix	string	false	Will suffix the list item with the parameter’s value
current	boolean	false	Set to “true” to indicate the current page in a list of content navigational links
iconType	string	false	Adds an icon to the individual list item when set to the name of one of the available icons
attributes	object	false	HTML attributes (for example, data attributes) to add to list item
itemsList	`Array<ListItem>`	false	Settings for each list item

HTML

<ul class="ons-list ons-list--prefix">
  <li class="ons-list__item">
    <span class="ons-list__prefix" aria-hidden="true">H1. </span>birth certificate
  </li>
  <li class="ons-list__item">
    <span class="ons-list__prefix" aria-hidden="true">H2. </span>national insurance number
  </li>
  <li class="ons-list__item">
    <span class="ons-list__prefix" aria-hidden="true">H3. </span>passport
  </li>
</ul>

Suffixed list

The suffix list works the same as the prefix but just comes after the list item and the full stop isn’t included.

Example Suffixed List contents

Nunjucksfor Example Suffixed List
Nunjucks macro optionsfor Example Suffixed List
HTMLfor Example Suffixed List

Nunjucks

{% from "components/list/_macro.njk" import onsList %}
{{
    onsList({
        "itemsList": [
            {
                "text": 'birth certificate',
                "suffix": 'A'
            },
            {
                "text": 'national insurance number',
                "suffix": 'B'
            },
            {
                "text": 'passport',
                "suffix": 'C'
            }
        ]
    })
}}

Nunjucks macro options

Name	Type	Required	Description
element	string	false	The wrapping element for the list. If nothing is defined it will default to `<ul>`
id	string	false	The HTML `id` for the wrapping element
classes	string	false	Classes to be added to the wrapping element
itemsList	`Array<ListItem>`	true	Settings for each list item
variants	array or string	false	An array of values or single value (string) to adjust the component using available variants: “bare”, “dashed”, “inline”, "summary", and “languages”
iconPosition	string	false	Sets position of icon to “before” or “after” each list item
iconType	string	false	Adds an icon to all the list items when set to the name of one of the available icons. Requires `iconPosition` to be set.
iconSize	string	false	Icon size can be set to match the size of the list item text as detailed in the typography type scale.
attributes	object	false	HTML attributes (for example, data attributes) to add to wrapping element

ListItem
Name	Type	Required	Description
listClasses	string	false	Classes to be added to the list item
text	string	true	The text for the list item
title	string	false	The text for the list item - used for Craft CMS
navigationTitle	string	false	The text for the list item - used for Craft CMS
url	string	false	Wraps the list item text in a link with the set `href`
classes	string	false	Classes to be added to the list item link
target	string	false	Sets the HTML `target` attribute for the list item when `url` is set
screenreaderMessage	string	false	Sets a message to be read out by screen readers when `target` is set to “_blank” to open a new tab. Defaults to “opens in a new tab”.
external	boolean	false	Sets the list item as an external link
prefix	string	false	Will prefix the list item with the parameter’s value
suffix	string	false	Will suffix the list item with the parameter’s value
current	boolean	false	Set to “true” to indicate the current page in a list of content navigational links
iconType	string	false	Adds an icon to the individual list item when set to the name of one of the available icons
attributes	object	false	HTML attributes (for example, data attributes) to add to list item
itemsList	`Array<ListItem>`	false	Settings for each list item

HTML

<ul class="ons-list ons-list--suffix">
  <li class="ons-list__item"> birth certificate<span class="ons-list__suffix" aria-hidden="true">A</span>
  </li>
  <li class="ons-list__item"> national insurance number<span class="ons-list__suffix" aria-hidden="true">B</span>
  </li>
  <li class="ons-list__item"> passport<span class="ons-list__suffix" aria-hidden="true">C</span>
  </li>
</ul>

Inline list

Inline lists should be used to display a horizontal row of links, for example, a list of pages displayed in the transactional footer.

Example Inline List contents

Nunjucksfor Example Inline List
Nunjucks macro optionsfor Example Inline List
HTMLfor Example Inline List

Nunjucks

{% from "components/list/_macro.njk" import onsList %}
{{
    onsList({
        "variants": ['bare', 'inline'],
        "itemsList": [
            {
                "text": 'Contact us',
                "url": '#0'
            },
            {
                "text": 'Cookies and privacy',
                "url": '#0'
            },
            {
                "text": 'Terms and conditions',
                "url": '#0'
            }
        ]
    })
}}

Nunjucks macro options

Name	Type	Required	Description
element	string	false	The wrapping element for the list. If nothing is defined it will default to `<ul>`
id	string	false	The HTML `id` for the wrapping element
classes	string	false	Classes to be added to the wrapping element
itemsList	`Array<ListItem>`	true	Settings for each list item
variants	array or string	false	An array of values or single value (string) to adjust the component using available variants: “bare”, “dashed”, “inline”, "summary", and “languages”
iconPosition	string	false	Sets position of icon to “before” or “after” each list item
iconType	string	false	Adds an icon to all the list items when set to the name of one of the available icons. Requires `iconPosition` to be set.
iconSize	string	false	Icon size can be set to match the size of the list item text as detailed in the typography type scale.
attributes	object	false	HTML attributes (for example, data attributes) to add to wrapping element

ListItem
Name	Type	Required	Description
listClasses	string	false	Classes to be added to the list item
text	string	true	The text for the list item
title	string	false	The text for the list item - used for Craft CMS
navigationTitle	string	false	The text for the list item - used for Craft CMS
url	string	false	Wraps the list item text in a link with the set `href`
classes	string	false	Classes to be added to the list item link
target	string	false	Sets the HTML `target` attribute for the list item when `url` is set
screenreaderMessage	string	false	Sets a message to be read out by screen readers when `target` is set to “_blank” to open a new tab. Defaults to “opens in a new tab”.
external	boolean	false	Sets the list item as an external link
prefix	string	false	Will prefix the list item with the parameter’s value
suffix	string	false	Will suffix the list item with the parameter’s value
current	boolean	false	Set to “true” to indicate the current page in a list of content navigational links
iconType	string	false	Adds an icon to the individual list item when set to the name of one of the available icons
attributes	object	false	HTML attributes (for example, data attributes) to add to list item
itemsList	`Array<ListItem>`	false	Settings for each list item

HTML

<ul class="ons-list ons-list--bare ons-list--inline">
  <li class="ons-list__item">
    <a href="#0" class="ons-list__link">Contact us</a>
  </li>
  <li class="ons-list__item">
    <a href="#0" class="ons-list__link">Cookies and privacy</a>
  </li>
  <li class="ons-list__item">
    <a href="#0" class="ons-list__link">Terms and conditions</a>
  </li>
</ul>

Lists with icons

There is specific guidance on how to use the available set of icons.

List with icon prefix

This example uses "iconPosition": 'before' and the iconType parameter on this list to show the check before each item.

Example List With Icon Prefix contents

Nunjucksfor Example List With Icon Prefix
Nunjucks macro optionsfor Example List With Icon Prefix
HTMLfor Example List With Icon Prefix

Nunjucks

{% from "components/list/_macro.njk" import onsList %}
{{
    onsList({
        "iconPosition": "before",
        "iconType": "check",
        "itemsList": [
            {
                "text": "birth certificate"
            },
            {
                "text": "national insurance number"
            },
            {
                "text": "passport"
            }
        ]
    })
}}

Nunjucks macro options

Name	Type	Required	Description
element	string	false	The wrapping element for the list. If nothing is defined it will default to `<ul>`
id	string	false	The HTML `id` for the wrapping element
classes	string	false	Classes to be added to the wrapping element
itemsList	`Array<ListItem>`	true	Settings for each list item
variants	array or string	false	An array of values or single value (string) to adjust the component using available variants: “bare”, “dashed”, “inline”, "summary", and “languages”
iconPosition	string	false	Sets position of icon to “before” or “after” each list item
iconType	string	false	Adds an icon to all the list items when set to the name of one of the available icons. Requires `iconPosition` to be set.
iconSize	string	false	Icon size can be set to match the size of the list item text as detailed in the typography type scale.
attributes	object	false	HTML attributes (for example, data attributes) to add to wrapping element

ListItem
Name	Type	Required	Description
listClasses	string	false	Classes to be added to the list item
text	string	true	The text for the list item
title	string	false	The text for the list item - used for Craft CMS
navigationTitle	string	false	The text for the list item - used for Craft CMS
url	string	false	Wraps the list item text in a link with the set `href`
classes	string	false	Classes to be added to the list item link
target	string	false	Sets the HTML `target` attribute for the list item when `url` is set
screenreaderMessage	string	false	Sets a message to be read out by screen readers when `target` is set to “_blank” to open a new tab. Defaults to “opens in a new tab”.
external	boolean	false	Sets the list item as an external link
prefix	string	false	Will prefix the list item with the parameter’s value
suffix	string	false	Will suffix the list item with the parameter’s value
current	boolean	false	Set to “true” to indicate the current page in a list of content navigational links
iconType	string	false	Adds an icon to the individual list item when set to the name of one of the available icons
attributes	object	false	HTML attributes (for example, data attributes) to add to list item
itemsList	`Array<ListItem>`	false	Settings for each list item

HTML

<ul class="ons-list ons-list--icons">
  <li class="ons-list__item">
    <span class="ons-list__prefix" aria-hidden="true">
      <svg class="ons-icon" viewBox="0 0 13 10" xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor"
        role="img" title="ons-icon-check">
        <path
          d="M14.35,3.9l-.71-.71a.5.5,0,0,0-.71,0h0L5.79,10.34,3.07,7.61a.51.51,0,0,0-.71,0l-.71.71a.51.51,0,0,0,0,.71l3.78,3.78a.5.5,0,0,0,.71,0h0L14.35,4.6A.5.5,0,0,0,14.35,3.9Z"
          transform="translate(-1.51 -3.04)" />
      </svg></span>birth certificate
  </li>
  <li class="ons-list__item">
    <span class="ons-list__prefix" aria-hidden="true">
      <svg class="ons-icon" viewBox="0 0 13 10" xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor"
        role="img" title="ons-icon-check">
        <path
          d="M14.35,3.9l-.71-.71a.5.5,0,0,0-.71,0h0L5.79,10.34,3.07,7.61a.51.51,0,0,0-.71,0l-.71.71a.51.51,0,0,0,0,.71l3.78,3.78a.5.5,0,0,0,.71,0h0L14.35,4.6A.5.5,0,0,0,14.35,3.9Z"
          transform="translate(-1.51 -3.04)" />
      </svg></span>national insurance number
  </li>
  <li class="ons-list__item">
    <span class="ons-list__prefix" aria-hidden="true">
      <svg class="ons-icon" viewBox="0 0 13 10" xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor"
        role="img" title="ons-icon-check">
        <path
          d="M14.35,3.9l-.71-.71a.5.5,0,0,0-.71,0h0L5.79,10.34,3.07,7.61a.51.51,0,0,0-.71,0l-.71.71a.51.51,0,0,0,0,.71l3.78,3.78a.5.5,0,0,0,.71,0h0L14.35,4.6A.5.5,0,0,0,14.35,3.9Z"
          transform="translate(-1.51 -3.04)" />
      </svg></span>passport
  </li>
</ul>

List with icon suffix

This example uses "iconPosition": 'after' and the iconType parameter on this list to show the check after each item.

Example List With Icon Suffix contents

Nunjucksfor Example List With Icon Suffix
Nunjucks macro optionsfor Example List With Icon Suffix
HTMLfor Example List With Icon Suffix

Nunjucks

{% from "components/list/_macro.njk" import onsList %}
{{
    onsList({
        "iconPosition": "after",
        "iconType": "check",
        "itemsList": [
            {
                "text": "birth certificate"
            },
            {
                "text": "national insurance number"
            },
            {
                "text": "passport"
            }
        ]
    })
}}

Nunjucks macro options

Name	Type	Required	Description
element	string	false	The wrapping element for the list. If nothing is defined it will default to `<ul>`
id	string	false	The HTML `id` for the wrapping element
classes	string	false	Classes to be added to the wrapping element
itemsList	`Array<ListItem>`	true	Settings for each list item
variants	array or string	false	An array of values or single value (string) to adjust the component using available variants: “bare”, “dashed”, “inline”, "summary", and “languages”
iconPosition	string	false	Sets position of icon to “before” or “after” each list item
iconType	string	false	Adds an icon to all the list items when set to the name of one of the available icons. Requires `iconPosition` to be set.
iconSize	string	false	Icon size can be set to match the size of the list item text as detailed in the typography type scale.
attributes	object	false	HTML attributes (for example, data attributes) to add to wrapping element

ListItem
Name	Type	Required	Description
listClasses	string	false	Classes to be added to the list item
text	string	true	The text for the list item
title	string	false	The text for the list item - used for Craft CMS
navigationTitle	string	false	The text for the list item - used for Craft CMS
url	string	false	Wraps the list item text in a link with the set `href`
classes	string	false	Classes to be added to the list item link
target	string	false	Sets the HTML `target` attribute for the list item when `url` is set
screenreaderMessage	string	false	Sets a message to be read out by screen readers when `target` is set to “_blank” to open a new tab. Defaults to “opens in a new tab”.
external	boolean	false	Sets the list item as an external link
prefix	string	false	Will prefix the list item with the parameter’s value
suffix	string	false	Will suffix the list item with the parameter’s value
current	boolean	false	Set to “true” to indicate the current page in a list of content navigational links
iconType	string	false	Adds an icon to the individual list item when set to the name of one of the available icons
attributes	object	false	HTML attributes (for example, data attributes) to add to list item
itemsList	`Array<ListItem>`	false	Settings for each list item

HTML

<ul class="ons-list ons-list--icons">
  <li class="ons-list__item"> birth certificate<span class="ons-list__suffix" aria-hidden="true">
      <svg class="ons-icon" viewBox="0 0 13 10" xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor"
        role="img" title="ons-icon-check">
        <path
          d="M14.35,3.9l-.71-.71a.5.5,0,0,0-.71,0h0L5.79,10.34,3.07,7.61a.51.51,0,0,0-.71,0l-.71.71a.51.51,0,0,0,0,.71l3.78,3.78a.5.5,0,0,0,.71,0h0L14.35,4.6A.5.5,0,0,0,14.35,3.9Z"
          transform="translate(-1.51 -3.04)" />
      </svg></span>
  </li>
  <li class="ons-list__item"> national insurance number<span class="ons-list__suffix" aria-hidden="true">
      <svg class="ons-icon" viewBox="0 0 13 10" xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor"
        role="img" title="ons-icon-check">
        <path
          d="M14.35,3.9l-.71-.71a.5.5,0,0,0-.71,0h0L5.79,10.34,3.07,7.61a.51.51,0,0,0-.71,0l-.71.71a.51.51,0,0,0,0,.71l3.78,3.78a.5.5,0,0,0,.71,0h0L14.35,4.6A.5.5,0,0,0,14.35,3.9Z"
          transform="translate(-1.51 -3.04)" />
      </svg></span>
  </li>
  <li class="ons-list__item"> passport<span class="ons-list__suffix" aria-hidden="true">
      <svg class="ons-icon" viewBox="0 0 13 10" xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor"
        role="img" title="ons-icon-check">
        <path
          d="M14.35,3.9l-.71-.71a.5.5,0,0,0-.71,0h0L5.79,10.34,3.07,7.61a.51.51,0,0,0-.71,0l-.71.71a.51.51,0,0,0,0,.71l3.78,3.78a.5.5,0,0,0,.71,0h0L14.35,4.6A.5.5,0,0,0,14.35,3.9Z"
          transform="translate(-1.51 -3.04)" />
      </svg></span>
  </li>
</ul>

This example uses "variants": [ 'inline', 'social'], "iconPosition": 'before' and "iconSize": 'xxl' on the list, with the iconType parameter set on each item to show the social icons.

Open this example in a new tab(Example Inline List With Social Icon Prefix)

Example Inline List With Social Icon Prefix contents

Nunjucksfor Example Inline List With Social Icon Prefix
Nunjucks macro optionsfor Example Inline List With Social Icon Prefix
HTMLfor Example Inline List With Social Icon Prefix

Nunjucks

{% from "components/list/_macro.njk" import onsList %}
{{
    onsList({
        "variants": 'inline',
        "iconPosition": 'before',
        "iconSize": '2xl',
        "itemsList": [
            {
                "url": '#0',
                "text": 'Twitter',
                "iconType": 'twitter',
                "attributes": {
                    "rel": 'noreferrer external'
                }
            },
            {
                "url": '#0',
                "text": 'Facebook',
                "iconType": 'facebook',
                "attributes": {
                    "rel": 'noreferrer external'
                }
            },
            {
                "url": '#0',
                "text": 'Instagram',
                "iconType": 'instagram',
                "attributes": {
                    "rel": 'noreferrer external'
                }
            },
            {
                "url": '#0',
                "text": 'LinkedIn',
                "iconType": 'linkedin',
                "attributes": {
                    "rel": 'noreferrer external'
                }
            }
        ]
    })
}}

Nunjucks macro options

Name	Type	Required	Description
element	string	false	The wrapping element for the list. If nothing is defined it will default to `<ul>`
id	string	false	The HTML `id` for the wrapping element
classes	string	false	Classes to be added to the wrapping element
itemsList	`Array<ListItem>`	true	Settings for each list item
variants	array or string	false	An array of values or single value (string) to adjust the component using available variants: “bare”, “dashed”, “inline”, "summary", and “languages”
iconPosition	string	false	Sets position of icon to “before” or “after” each list item
iconType	string	false	Adds an icon to all the list items when set to the name of one of the available icons. Requires `iconPosition` to be set.
iconSize	string	false	Icon size can be set to match the size of the list item text as detailed in the typography type scale.
attributes	object	false	HTML attributes (for example, data attributes) to add to wrapping element

ListItem
Name	Type	Required	Description
listClasses	string	false	Classes to be added to the list item
text	string	true	The text for the list item
title	string	false	The text for the list item - used for Craft CMS
navigationTitle	string	false	The text for the list item - used for Craft CMS
url	string	false	Wraps the list item text in a link with the set `href`
classes	string	false	Classes to be added to the list item link
target	string	false	Sets the HTML `target` attribute for the list item when `url` is set
screenreaderMessage	string	false	Sets a message to be read out by screen readers when `target` is set to “_blank” to open a new tab. Defaults to “opens in a new tab”.
external	boolean	false	Sets the list item as an external link
prefix	string	false	Will prefix the list item with the parameter’s value
suffix	string	false	Will suffix the list item with the parameter’s value
current	boolean	false	Set to “true” to indicate the current page in a list of content navigational links
iconType	string	false	Adds an icon to the individual list item when set to the name of one of the available icons
attributes	object	false	HTML attributes (for example, data attributes) to add to list item
itemsList	`Array<ListItem>`	false	Settings for each list item

HTML

<ul class="ons-list ons-list--inline ons-list--icons">
  <li class="ons-list__item" rel="noreferrer external">
    <span class="ons-list__prefix" aria-hidden="true">
      <svg class="ons-icon ons-icon--2xl" id="icon-twitter" viewBox="0 0 90.01 90.01" xmlns="http://www.w3.org/2000/svg"
        focusable="false" aria-hidden="true" role="img" title="ons-icon-twitter">
        <polygon points="24.89,23.01 57.79,66.99 65.24,66.99 32.34,23.01" />
        <path
          d="M 45 0 L 45 0 C 20.147 0 0 20.147 0 45 v 0 c 0 24.853 20.147 45 45 45 h 0 c 24.853 0 45 -20.147 45 -45 v 0 C 90 20.147 69.853 0 45 0 z M 56.032 70.504 L 41.054 50.477 L 22.516 70.504 h -4.765 L 38.925 47.63 L 17.884 19.496 h 16.217 L 47.895 37.94 l 17.072 -18.444 h 4.765 L 50.024 40.788 l 22.225 29.716 H 56.032 z" />
      </svg></span><a href="#0" class="ons-list__link">Twitter</a>
  </li>
  <li class="ons-list__item" rel="noreferrer external">
    <span class="ons-list__prefix" aria-hidden="true">
      <svg class="ons-icon ons-icon--2xl" id="icon-facebook" viewBox="0 0 32 32" xmlns="http://www.w3.org/2000/svg"
        focusable="false" aria-hidden="true" role="img" title="ons-icon-facebook">
        <path
          d="M32,16.0986285 C32.0009185,7.5342974 25.337417,0.468462963 16.8372092,0.0203294753 C8.33700136,-0.427804013 0.97607758,5.89865855 0.0874346352,14.4161886 C-0.801208309,22.9337186 5.09355054,30.6602611 13.5009524,31.9979281 L13.5009524,20.7518951 L9.44,20.7518951 L9.44,16.0986285 L13.5009524,16.0986285 L13.5009524,12.549267 C13.5009524,8.5169471 15.8857143,6.28613892 19.5428571,6.28613892 C20.742535,6.30277426 21.9393895,6.40782423 23.1238095,6.60044523 L23.1238095,10.5637711 L21.1047619,10.5637711 C19.1161905,10.5637711 18.4990476,11.8056643 18.4990476,13.0782216 L18.4990476,16.0986285 L22.9409524,16.0986285 L22.2247619,20.7518951 L18.4990476,20.7518951 L18.4990476,31.9979281 C26.2735701,30.760956 31.9991507,24.0182672 32,16.0986285 L32,16.0986285 Z" />
      </svg></span><a href="#0" class="ons-list__link">Facebook</a>
  </li>
  <li class="ons-list__item" rel="noreferrer external">
    <span class="ons-list__prefix" aria-hidden="true">
      <svg class="ons-icon ons-icon--2xl" id="icon-instagram" viewBox="0 0 32 32" xmlns="http://www.w3.org/2000/svg"
        focusable="false" aria-hidden="true" role="img" title="ons-icon-title">
        <path
          d="M21.34,9.46c0.66,0,1.2,0.54,1.2,1.2c0,0.66-0.54,1.2-1.2,1.2c-0.66,0-1.2-0.54-1.2-1.2C20.14,10,20.68,9.46,21.34,9.46z M16,12.67c-1.84,0-3.33,1.49-3.33,3.33c0,1.84,1.49,3.33,3.33,3.33c1.84,0,3.33-1.49,3.33-3.33C19.33,14.16,17.84,12.67,16,12.67z M16,10.86c2.84,0,5.14,2.3,5.14,5.14c0,2.84-2.3,5.14-5.14,5.14c-2.84,0-5.14-2.3-5.14-5.14C10.86,13.16,13.16,10.86,16,10.86z M16.56,7.8h-1.11c-2.17,0-2.51,0.01-3.49,0.06c-0.97,0.04-1.5,0.21-1.86,0.34C9.64,8.39,9.3,8.6,8.95,8.95C8.6,9.3,8.39,9.64,8.2,10.1c-0.14,0.35-0.3,0.88-0.34,1.86c-0.04,0.98-0.06,1.32-0.06,3.49v1.11c0,2.17,0.01,2.51,0.06,3.49c0.04,0.97,0.21,1.5,0.34,1.86c0.18,0.47,0.4,0.8,0.75,1.15c0.35,0.35,0.68,0.57,1.15,0.75c0.35,0.14,0.88,0.3,1.86,0.34c0.94,0.04,1.29,0.06,3.23,0.06h1.61c1.94,0,2.3-0.02,3.23-0.06c0.97-0.04,1.5-0.21,1.86-0.34c0.47-0.18,0.8-0.4,1.15-0.75c0.35-0.35,0.57-0.68,0.75-1.15c0.14-0.35,0.3-0.88,0.34-1.86c0.04-0.94,0.06-1.29,0.06-3.23v-1.61c0-1.94-0.02-2.3-0.06-3.23c-0.04-0.97-0.21-1.5-0.34-1.86c-0.18-0.47-0.4-0.8-0.75-1.15C22.7,8.6,22.36,8.39,21.9,8.2c-0.35-0.14-0.88-0.3-1.86-0.34C19.06,7.82,18.72,7.8,16.56,7.8z M17.03,6c1.8,0,2.18,0.02,3.1,0.06c1.06,0.05,1.79,0.22,2.43,0.46c0.66,0.26,1.22,0.6,1.77,1.15c0.56,0.56,0.9,1.11,1.15,1.77c0.25,0.64,0.42,1.36,0.46,2.43c0.05,0.99,0.06,1.35,0.06,3.58v1.09c0,2.22-0.01,2.59-0.06,3.58c-0.05,1.06-0.22,1.79-0.46,2.43c-0.26,0.66-0.6,1.22-1.15,1.77c-0.56,0.56-1.11,0.9-1.77,1.15c-0.64,0.25-1.36,0.42-2.43,0.46C19.13,25.99,18.77,26,16.55,26h-1.09c-2.22,0-2.59-0.01-3.58-0.06c-1.06-0.05-1.79-0.22-2.43-0.46c-0.66-0.26-1.22-0.6-1.77-1.15c-0.56-0.56-0.9-1.11-1.15-1.77c-0.25-0.64-0.42-1.36-0.46-2.43C6.02,19.21,6,18.83,6,17.03v-2.06c0-1.8,0.02-2.18,0.06-3.1c0.05-1.06,0.22-1.79,0.46-2.43c0.26-0.66,0.6-1.22,1.15-1.77c0.56-0.56,1.11-0.9,1.77-1.15c0.64-0.25,1.36-0.42,2.43-0.46C12.79,6.02,13.17,6,14.97,6H17.03z M16,0C7.16,0,0,7.16,0,16s7.16,16,16,16s16-7.16,16-16c0-4.24-1.69-8.31-4.69-11.31S20.24,0,16,0z" />
      </svg></span><a href="#0" class="ons-list__link">Instagram</a>
  </li>
  <li class="ons-list__item" rel="noreferrer external">
    <span class="ons-list__prefix" aria-hidden="true">
      <svg class="ons-icon ons-icon--2xl" id="icon-linkedin" viewBox="0 0 32 32" xmlns="http://www.w3.org/2000/svg"
        focusable="false" aria-hidden="true" role="img" title="ons-icon-linkedin">
        <path
          d="M16,-3.41060513e-13 C20.2434638,-3.41060513e-13 24.3131264,1.68570945 27.3137085,4.6862915 C30.3142906,7.68687356 32,11.7565362 32,16 C32,24.836556 24.836556,32 16,32 C7.163444,32 0,24.836556 0,16 C0,7.163444 7.163444,-3.41060513e-13 16,-3.41060513e-13 Z M11.3505859,12.4641113 L7.45385744,12.4641113 L7.45385744,24.1875 L11.3505859,24.1875 L11.3505859,12.4641113 Z M20.9152832,12.1889649 C18.8479004,12.1889649 17.9213867,13.3251953 17.4035644,14.1240234 L17.4035644,14.1240234 L17.4035644,12.4641113 L13.5070801,12.4641113 C13.5212538,12.7696262 13.5275532,13.809993 13.5292593,15.1533871 L13.5293118,16.8832762 C13.5292156,16.9843911 13.5291048,17.0860852 13.5289803,17.1882303 L13.5280782,17.8054916 L13.5280782,17.8054916 L13.5268961,18.427439 C13.5216699,20.9164121 13.5108442,23.3704557 13.5078578,24.0208157 L13.5070801,24.1875 L17.4035644,24.1875 L17.4035644,17.640625 C17.4035644,17.2902832 17.4287109,16.9401856 17.5317382,16.6896972 C17.8134766,15.9897461 18.4545899,15.2646484 19.5310059,15.2646484 C20.940918,15.2646484 21.5051269,16.3395996 21.5051269,17.9157715 L21.5051269,17.9157715 L21.5051269,24.1875 L25.4013672,24.1875 L25.4013672,17.465332 C25.4013672,13.8645019 23.4790039,12.1889649 20.9152832,12.1889649 Z M9.42822263,6.8125 C8.09521488,6.8125 7.22363281,7.68774412 7.22363281,8.83813475 C7.22363281,9.96313475 8.06933594,10.8632812 9.37695313,10.8632812 L9.37695313,10.8632812 L9.40234375,10.8632812 C10.7612305,10.8632812 11.6069336,9.96313475 11.6069336,8.83813475 C11.581543,7.68774412 10.7612305,6.8125 9.42822263,6.8125 Z" />
      </svg>
    </span><a href="#0" class="ons-list__link">LinkedIn</a>
  </li>
</ul>

Summary list

Summary lists should be used to present a clear list of values to the user after they have completed a section or the entire questionnaire.

Example Summary List contents

Nunjucksfor Example Summary List
Nunjucks macro optionsfor Example Summary List
HTMLfor Example Summary List

Nunjucks

{% from "components/list/_macro.njk" import onsList %}
{{
    onsList({
        "iconPosition": "before",
        "variants": "summary",
        "itemsList": [
            {
                "text": 'birth certificate',
                "iconType": "check"
            },
            {
                "text": 'national insurance number'
            },
            {
                "text": 'passport'
            }
        ]
    })
}}

Nunjucks macro options

Name	Type	Required	Description
element	string	false	The wrapping element for the list. If nothing is defined it will default to `<ul>`
id	string	false	The HTML `id` for the wrapping element
classes	string	false	Classes to be added to the wrapping element
itemsList	`Array<ListItem>`	true	Settings for each list item
variants	array or string	false	An array of values or single value (string) to adjust the component using available variants: “bare”, “dashed”, “inline”, "summary", and “languages”
iconPosition	string	false	Sets position of icon to “before” or “after” each list item
iconType	string	false	Adds an icon to all the list items when set to the name of one of the available icons. Requires `iconPosition` to be set.
iconSize	string	false	Icon size can be set to match the size of the list item text as detailed in the typography type scale.
attributes	object	false	HTML attributes (for example, data attributes) to add to wrapping element

ListItem
Name	Type	Required	Description
listClasses	string	false	Classes to be added to the list item
text	string	true	The text for the list item
title	string	false	The text for the list item - used for Craft CMS
navigationTitle	string	false	The text for the list item - used for Craft CMS
url	string	false	Wraps the list item text in a link with the set `href`
classes	string	false	Classes to be added to the list item link
target	string	false	Sets the HTML `target` attribute for the list item when `url` is set
screenreaderMessage	string	false	Sets a message to be read out by screen readers when `target` is set to “_blank” to open a new tab. Defaults to “opens in a new tab”.
external	boolean	false	Sets the list item as an external link
prefix	string	false	Will prefix the list item with the parameter’s value
suffix	string	false	Will suffix the list item with the parameter’s value
current	boolean	false	Set to “true” to indicate the current page in a list of content navigational links
iconType	string	false	Adds an icon to the individual list item when set to the name of one of the available icons
attributes	object	false	HTML attributes (for example, data attributes) to add to list item
itemsList	`Array<ListItem>`	false	Settings for each list item

HTML

<ul class="ons-list ons-list--summary ons-list--icons">
  <li class="ons-list__item">
    <span class="ons-list__prefix ons-list__prefix--icon-check" aria-hidden="true">
      <svg class="ons-icon" viewBox="0 0 13 10" xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor"
        role="img" title="ons-icon-check">
        <path
          d="M14.35,3.9l-.71-.71a.5.5,0,0,0-.71,0h0L5.79,10.34,3.07,7.61a.51.51,0,0,0-.71,0l-.71.71a.51.51,0,0,0,0,.71l3.78,3.78a.5.5,0,0,0,.71,0h0L14.35,4.6A.5.5,0,0,0,14.35,3.9Z"
          transform="translate(-1.51 -3.04)" />
      </svg></span>birth certificate
  </li>
  <li class="ons-list__item">
    <span class="ons-list__prefix" aria-hidden="true">
    </span>national insurance number
  </li>
  <li class="ons-list__item">
    <span class="ons-list__prefix" aria-hidden="true">
    </span>passport
  </li>
</ul>

Highlighting

Use highlighting to add emphasis to particular content that a user may otherwise miss.

To apply highlights:

in a heading, use the semantic strong tag (<strong>)
in other text that is not a heading, use the class .ons-highlight
in a document list search result, use the semantic tag <mark>

Example Highlighting contents

HTMLfor Example Highlighting

HTML

<h1>What was the value of the business’s total sales of <strong>food</strong>?</h1>
<h2>Of the <strong>423</strong> employees how many were part-time?</h2>
<h3>You said <strong>0</strong> visitors are staying overnight here on Sunday 21 March 2021</h3>

Quotes

Use when displaying a short quote.

Nunjucks

{% from "components/quote/_macro.njk" import onsQuote %}
{{-
    onsQuote({
        "text": 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
        "ref": 'A N Other'
    })
-}}

Nunjucks macro options

Name	Type	Required	Description
text	string	true	Sets the text for the quote
textFontSize	string	false	Sets the font-size suffix to append to `ons-u-fs-` as detailed in the typography type scale. Defaults to “l”.
ref	string	false	Sets the source of the quote

HTML

<blockquote class="ons-quote">
  <svg class="ons-icon" viewBox="0 0 14 10" xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor"
    role="img" title="ons-icon-quote">
    <path d="M13.44.77h-3l-2 4v6h6v-6h-3l2-4zm-8 0h-3l-2 4v6h6v-6h-3l2-4z" transform="translate(-0.44 -0.77)" />
  </svg><span class="ons-quote__text ons-u-fs-l">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</span>
  <span class="ons-quote__ref">&mdash; A N Other</span>
</blockquote>

Addresses

Use when displaying an address.

Example Address Output contents

Nunjucksfor Example Address Output
Nunjucks macro optionsfor Example Address Output
HTMLfor Example Address Output

Nunjucks

{% from "components/address-output/_macro.njk" import onsAddressOutput %}
{{
    onsAddressOutput({
        "unit": 'Unit 5',
        "organisation": 'Trescos',
        "line1": 'Abingdon Road',
        "line2": 'Goathill',
        "town": 'Barry',
        "postcode": 'AB12 6UH'
    })
}}

Nunjucks macro options

Name	Type	Required	Description
classes	string	false	Classes to add to the wrapping `div`
unit	string	false	Text for the Unit field
organisation	string	false	Text for the Organisation field
line1	string	false	Text for the Address line 1 field
line2	string	false	Text for the Address line 2 field
town	string	false	Text for the Town or city field
postcode	string	false	Text for the Postcode field

HTML

<div class="ons-address-output">
  <p class="ons-address-output__lines">
    <span class="ons-address-output__unit">Unit 5</span><br />
    <span class="ons-address-output__organisation">Trescos</span><br />
    <span class="ons-address-output__line1">Abingdon Road</span><br />
    <span class="ons-address-output__line2">Goathill</span><br />
    <span class="ons-address-output__town">Barry</span><br />
    <span class="ons-address-output__postcode">AB12 6UH</span>
  </p>
</div>

Indented text

Use when you need information to stand out from the rest of the content on a page, for example, when providing contact information.

Example Text Indent contents

Nunjucksfor Example Text Indent
Nunjucks macro optionsfor Example Text Indent
HTMLfor Example Text Indent

Nunjucks

{% from "components/text-indent/_macro.njk" import onsTextIndent %}
{{-
    onsTextIndent({
        "text": '<p>Telephone: 0800 141 2021<br>Monday to Friday, 8 am to 7pm<br>Saturday, 8am to 4pm</p>'
    })
-}}

Nunjucks macro options

Name	Type	Required	Description
text	string	true	The content of the component. This can contain HTML.

HTML

<div class="ons-text-indent">
  <p>Telephone: 0800 141 2021<br>Monday to Friday, 8 am to 7pm<br>Saturday, 8am to 4pm</p>
</div>

Help improve this page

Let us know how we could improve this page, or share your user research findings. Discuss this page on GitHub (opens in a new tab)

Cookies on ons.gov.uk

Style Typography

Overview

Font

Font weights

Type scale

Headings

Breakpoint headings

Paragraphs

Links

Links that open in a new tab

External Links

Example External Link contents

Nunjucks

Nunjucks macro options

HTML

Lists

Bulleted list (default)

Nunjucks

Nunjucks macro options

HTML

Numbered list

Nunjucks

Nunjucks macro options

HTML

Bare list

Nunjucks

Nunjucks macro options

HTML

Dashed list

Example Dashed List contents

Nunjucks

Nunjucks macro options

HTML

Prefixed list

Example Prefixed List contents

Nunjucks

Nunjucks macro options

HTML

Suffixed list

Example Suffixed List contents

Nunjucks

Nunjucks macro options

HTML

Inline list

Example Inline List contents

Nunjucks

Nunjucks macro options

HTML

Lists with icons

List with icon prefix

Example List With Icon Prefix contents

Nunjucks

Nunjucks macro options

HTML

List with icon suffix

Example List With Icon Suffix contents

Nunjucks

Nunjucks macro options

HTML

Inline list with social media icon prefix

Example Inline List With Social Icon Prefix contents

Nunjucks

Nunjucks macro options

HTML

Summary list

Example Summary List contents

Nunjucks

Nunjucks macro options

HTML

Highlighting

Example Highlighting contents

HTML

Quotes

Example Quote contents

Nunjucks

Nunjucks macro options

HTML

Addresses

Example Address Output contents