Skip to main content

Style Typography

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  , defaulting to stylistic set 2 (for open g’s).

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 stack: “Open Sans”, “Helvetica Neue”, Helvetica, Arial, sans-serif

Type scale

Using the type scale classes on text elements, the type is sized appropriately for the following breakpoints:

Viewport < 740 Viewport >= 740

ons-u-fs-xxxl

Open Sans Bold - 1.7rem/32px

ons-u-fs-xxxl

Open Sans Bold - 2.6rem/48px

ons-u-fs-xxl

Open Sans Bold - 1.5rem/28px

ons-u-fs-xxl

Open Sans Bold - 2rem/36px

ons-u-fs-xl

Open Sans Bold - 1.4rem/26px

ons-u-fs-xl

Open Sans Bold - 1.6rem/30px

ons-u-fs-l

Open Sans Bold - 1.3rem/24px

ons-u-fs-l

Open Sans Bold - 1.4rem/26px

ons-u-fs-m

Open Sans Bold - 1.1rem/20px

ons-u-fs-m

Open Sans Bold - 1.2rem/22px

ons-u-fs-r–b

Open Sans Bold - 1rem/18px

ons-u-fs-r–b

Open Sans Bold - 1rem/18px

ons-u-fs-r

Open Sans Regular - 1rem/18px

ons-u-fs-r

Open Sans Regular - 1rem/18px

ons-u-fs-s–b

Open Sans Bold - 0.7rem/14px

ons-u-fs-s–b

Open Sans Bold - 0.7rem/14px

ons-u-fs-s

Open Sans Regular - 0.7rem/14px

ons-u-fs-s

Open Sans Regular - 0.7rem/14px

Font weights

  • Bold: 700
  • Regular: 400

Headings

Heading defaults are as follows:

<h1>Heading 1 (ons-u-fs-xl)</h1>
<h2>Heading 2 (ons-u-fs-l)</h2>
<h3>Heading 3 (ons-u-fs-m)</h3>
<h4>Heading 4 (ons-u-fs-r--b)</h4>
<p class="ons-u-fs-s--b">Small (ons-u-fs-s--b)</p>
<p class="ons-u-fs-s">Small (ons-u-fs-s)</p>
<h1>Heading 1 (ons-u-fs-xl)</h1>
<h2>Heading 2 (ons-u-fs-l)</h2>
<h3>Heading 3 (ons-u-fs-m)</h3>
<h4>Heading 4 (ons-u-fs-r--b)</h4>
<p class="ons-u-fs-s--b">Small (ons-u-fs-s--b)</p>
<p class="ons-u-fs-s">Small (ons-u-fs-s)</p>

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

This text will change font size depending on viewport width

Paragraphs

The base font size for paragraphs is 18px.

<p>This is a paragraph of text with some <strong>bold text</strong>. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
<p class="ons-u-fs-r">Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum. Nullam id dolor id nibh ultricies vehicula ut id elit. Nullam quis risus eget urna mollis ornare vel eu leo. Fusce dapibus, tellus ac cursus commodo, tortor mauris condimentum nibh, ut fermentum massa justo sit amet risus. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec ullamcorper nulla non metus auctor fringilla. Donec id elit non mi porta gravida at eget metus.</p>
<p>This is a paragraph of text with some <strong>bold text</strong>. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
<p class="ons-u-fs-r">Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum. Nullam id dolor id nibh ultricies vehicula ut id elit. Nullam quis risus eget urna mollis ornare vel eu leo. Fusce dapibus, tellus ac cursus commodo, tortor mauris condimentum nibh, ut fermentum massa justo sit amet risus. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec ullamcorper nulla non metus auctor fringilla. Donec id elit non mi porta gravida at eget metus.</p>

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.

<a href="#0">link</a>
<a href="#0">link</a>

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.

<a href="#1" class="ons-external-link" target="_blank" rel="noopener">Link to an external website<span class="ons-external-link__icon">&nbsp;<svg id="external-link" class="ons-svg-icon" viewBox="0 0 12 12" xmlns="http://www.w3.org/2000/svg">
      <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></a>
{% from "components/external-link/_macro.njk" import onsExternalLink %}

{{
    onsExternalLink({
        "url": "#1",
        "linkText": "Link to an external website"
    })
}}
Name Type Required Description
url string true URL of the link
linkText string true Text of the link
{# Icon needed to be directly put here instead of calling macro to solve an issue with extra space on the end of links being underlined #}
{% macro onsExternalLink(params) %}
    <a href="{{ params.url }}" class="ons-external-link{% if params.classes is defined and params.classes %} {{ params.classes }}{% endif %}" target="_blank" rel="noopener">{{- params.linkText | safe -}}<span class="ons-external-link__icon">&nbsp;<svg id="external-link" class="ons-svg-icon" viewBox="0 0 12 12" xmlns="http://www.w3.org/2000/svg">
        <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></a>
{% endmacro %}
.ons-external-link {
  &__icon {
    visibility: hidden;
    white-space: nowrap;
  }
  .ons-svg-icon {
    fill: $color-grey-100;
    margin: 0 0 0 0.25rem;
    padding-bottom: 0.1rem;
    visibility: visible;
  }
  &:focus {
    .ons-svg-icon {
      fill: $color-black;
    }
  }
  &:hover {
    .ons-svg-icon {
      fill: $color-text-link-hover;
      .ons-footer & {
        fill: $color-black;
      }
    }
  }
}

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.

<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>
{% from "components/lists/_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'
            }
        ]
    })
}}
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 id for the wrapping element
classes string false Classes to be added to the wrapping element
itemsList Array<ListItem> true An array of items to show in the list
variants array or string false An array of values or single value (string) to adjust the ‘list’ display using available variants - bare, dashed, inline, social, languages
iconPosition string true Sets position of icon to before or after all the list items
iconSize string true Icon size can be set to m, l, xl, xxl
iconType string true Adds an icon to all the list items when set to the name of one of the available icons

ListItem

Name Type Required Description
text string true The text for the list item
title string false The text for the list item - only used for craft
url string false Will wrap the text in a link
listClasses string false Classes to be added to the list item
variants string false Used for variations. Available variants values: inPageLink for use with error lists when a url is also provided
rel string false allows setting of rel attribute for list item links
target string false If url is provided this will set the target for that link
screenreaderMessage string false Sets a message to be read out by screen readers when target is set to _blank and link opens in a new tab. Defaults to this link will open in a new tab if not set
index boolean false Will prefix the list item with index number if set to true
external boolean false Will style the item like an external link
prefix string true Will prefix the list item with whatever prefix is set to
suffix string true Will suffix the list item with whatever suffix is set to
iconType string true Adds an icon to the list item when set to the name of one of the available icons
{% macro onsList(params) %}
    {% set variants = params.variants if params.variants else '' %}
    {% set listLength = params.itemsList | length %}

    {% if params.itemsList[0] is defined and params.itemsList[0].prefix %}
        {% set otherClasses = 'ons-list--bare ons-list--prefix' %}
    {% elif params.itemsList[0] is defined and params.itemsList[0].suffix %}
        {% set otherClasses = 'ons-list--bare ons-list--suffix' %}
    {% elif params.itemsList[0] is defined and params.iconPosition is defined and params.iconPosition %}
        {% set otherClasses = 'ons-list--bare ons-list--icons' %}
        {% set iconType = params.iconType if params.iconType else '' %}
    {% else %}
        {% set otherClasses = '' %}
    {% endif %}

    {% if listLength < 2 %}
        {% set listEl = 'p' %}
    {% elif params.element is defined and params.element %}
        {% set listEl = params.element | lower %}
    {% else %}
        {% set listEl = 'ul' %}
    {% endif %}

    <{{listEl}} {% if params.id is defined and params.id %}id="{{ params.id }} "{% endif %}class="{% if listLength > 1 %}ons-list{% endif %}{% if params.classes is defined and params.classes %} {{ params.classes -}}{% endif %}{% if params.variants is defined and params.variants %}{% if params.variants is not string %}{% for variant in params.variants %} ons-list--{{ variant }}{% endfor %}{% else %} ons-list--{{ params.variants }}{% endif %}{% endif %}{% if otherClasses %} {{ otherClasses -}}{% endif %}">
        {%- for item in (params.itemsList if params.itemsList is iterable else params.itemsList.items()) -%}
            {% if listLength > 1 %}<li class="ons-list__item{% if item.listClasses is defined and item.listClasses %} {{ item.listClasses }}{% endif %}"{% if item.current is defined and item.current %} aria-current="true"{% endif %}>{% endif %}

                {% set itemText = item.text %}

                {% if params.itemsList[0] is defined and item.iconType is defined and item.iconType %}
                    {% set iconType = item.iconType if item.iconType else '' %}
                {% endif %}

                {# For Craft support we also support title and navigation title #}
                {% if item.navigationTitle is defined and item.navigationTitle %}
                    {% set itemText = item.navigationTitle %}
                {% elif item.title is defined and item.title %}
                    {% set itemText = item.title %}
                {% endif %}

                {%- if item.index is defined and item.index or item.prefix is defined and item.prefix or (params.iconPosition is defined and params.iconPosition == 'before') -%}
                    <span class="ons-list__prefix"{% if listEl != 'ol' %} aria-hidden="true"{% endif %}>
                    {%- if item.prefix is defined and item.prefix -%}
                        {{- item.prefix -}}.
                    {%- elif (item.index is defined and item.index and listEl != 'ol') or (item.index is defined and item.index and listEl == 'ol' and 'bare' in variants) -%}
                        {{- loop.index -}}.
                    {% elif params.iconPosition is defined and params.iconPosition == 'before' %}
                        {% from "components/icons/_macro.njk" import onsIcon %}
                        {{
                            onsIcon({
                                "iconType": iconType,
                                "iconSize": params.iconSize
                            })
                        }}
                    {%- endif -%}
                    </span>
                {%- endif -%}
                {%- if item.url is defined and item.url and item.current != true -%}
                    {%- if item.external is defined and item.external -%}
                        {% from "components/external-link/_macro.njk" import onsExternalLink %}
                        {{
                            onsExternalLink({
                                "url": item.url,
                                "linkText": itemText
                            })
                        }}
                    {%- else -%}
                        <a href="{{ item.url }}" class="ons-list__link {% if item.variant == 'inPageLink' %}ons-js-inpagelink {% endif %} {{ item.classes }}"{% if item.index is defined and item.index %} data-qa="list-item-{{ loop.index }}"{% endif %}{% if item.target is defined and item.target %} target="{{ item.target }}"{% endif %}{% if item.rel is defined and item.rel %} rel="{{ item.rel }}"{% endif %}>
                            {%- if item.prefix is defined and item.prefix -%}<span class="ons-u-vh">{{- item.prefix -}}</span>{%- endif -%} {{- itemText | safe -}}
                            {%- if item.target is defined and item.target == "_blank" -%}<span class="ons-u-vh">{{- item.screenreaderMessage | default("this link will open in a new tab") -}}</span>{%- endif -%}
                        </a>
                    {%- endif -%}
                {%- else -%}
                    {{- itemText | safe -}}
                {%- endif -%}
                {%- if item.suffix is defined and item.suffix or (params.iconPosition is defined and params.iconPosition == 'after') -%}
                    <span class="ons-list__suffix"{% if listEl != 'ol' %} aria-hidden="true"{% endif %}>
                    {%- if item.suffix is defined and item.suffix -%}
                        {{- item.suffix -}}
                    {%- elif (item.index is defined and item.index and listEl != 'ol') or (item.index is defined and item.index and listEl == 'ol' and 'bare' in variants) -%}
                        {{- loop.index -}}
                    {% elif params.iconPosition is defined and params.iconPosition == 'after' %}
                        {% from "components/icons/_macro.njk" import onsIcon %}
                        {{
                            onsIcon({
                                "iconType": iconType,
                                "iconSize": params.iconSize
                            })
                        }}
                    {%- endif -%} </span>
                {%- endif -%}
            {% if listLength > 1 %}</li>{%- endif -%}
        {%- endfor -%}
    </{{listEl}}>
{% endmacro %}
.ons-list {
  margin: 0 0 1rem;
  padding: 0 0 0 1.5rem;

  &__item {
    &:last-child {
      margin-bottom: 0;
    }
  }

  &--spacious {
    .ons-list__item {
      margin: 0 0 1.5rem;
    }
  }

  &--bare {
    list-style: none;
    padding-left: 0;
  }

  &--dashed {
    @extend .ons-list--bare;
    .ons-list__item {
      margin-left: 25px;
      position: relative;
      &::before {
        border-top: 1px solid $color-black;
        content: '';
        left: 0;
        margin-left: -25px;
        position: absolute;
        top: 14px;
        width: 15px;
      }
    }
  }

  &__link {
    display: inline-block;
    margin-right: 1rem;
    vertical-align: top;
    white-space: normal;
  }

  &__prefix {
    margin-right: 0.5rem;
  }

  &__suffix {
    margin-left: 0.5rem;
  }

  &__prefix,
  &__suffix {
    font-family: $font-mono;
  }

  &--prefix &,
  &--suffix &,
  &--icons & {
    &__item {
      align-items: flex-start;
      display: flex;
    }
  }

  &--social & {
    &__item {
      align-items: center;
    }
  }

  &--icons {
    margin-bottom: 0;
    .ons-list__item {
      margin-bottom: 0.5rem;
    }
  }

  &--languages {
    margin-bottom: 0;
    .ons-list__link {
      margin-right: 0;
    }
  }
}

@include bp-suffix('ons-list--inline') {
  &:not(.ons-list--icons) {
    margin: 0 1rem 0 0;
    .ons-list__item {
      display: inline-block;
      margin: 0 1rem 0 0;
      vertical-align: top;
    }
  }

  &.ons-list--icons {
    align-items: center;
    display: flex;
    flex-wrap: wrap;
  }
}

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.

<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>
{% from "components/lists/_macro.njk" import onsList %}
{{
    onsList({
        "element": 'ol',
        "itemsList": [
            {
                "text": 'Introduction.'
            },
            {
                "text": 'Questionnaire.'
            },
            {
                "text": 'Summary.'
            }
        ]
    })
}}
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 id for the wrapping element
classes string false Classes to be added to the wrapping element
itemsList Array<ListItem> true An array of items to show in the list
variants array or string false An array of values or single value (string) to adjust the ‘list’ display using available variants - bare, dashed, inline, social, languages
iconPosition string true Sets position of icon to before or after all the list items
iconSize string true Icon size can be set to m, l, xl, xxl
iconType string true Adds an icon to all the list items when set to the name of one of the available icons

ListItem

Name Type Required Description
text string true The text for the list item
title string false The text for the list item - only used for craft
url string false Will wrap the text in a link
listClasses string false Classes to be added to the list item
variants string false Used for variations. Available variants values: inPageLink for use with error lists when a url is also provided
rel string false allows setting of rel attribute for list item links
target string false If url is provided this will set the target for that link
screenreaderMessage string false Sets a message to be read out by screen readers when target is set to _blank and link opens in a new tab. Defaults to this link will open in a new tab if not set
index boolean false Will prefix the list item with index number if set to true
external boolean false Will style the item like an external link
prefix string true Will prefix the list item with whatever prefix is set to
suffix string true Will suffix the list item with whatever suffix is set to
iconType string true Adds an icon to the list item when set to the name of one of the available icons
{% macro onsList(params) %}
    {% set variants = params.variants if params.variants else '' %}
    {% set listLength = params.itemsList | length %}

    {% if params.itemsList[0] is defined and params.itemsList[0].prefix %}
        {% set otherClasses = 'ons-list--bare ons-list--prefix' %}
    {% elif params.itemsList[0] is defined and params.itemsList[0].suffix %}
        {% set otherClasses = 'ons-list--bare ons-list--suffix' %}
    {% elif params.itemsList[0] is defined and params.iconPosition is defined and params.iconPosition %}
        {% set otherClasses = 'ons-list--bare ons-list--icons' %}
        {% set iconType = params.iconType if params.iconType else '' %}
    {% else %}
        {% set otherClasses = '' %}
    {% endif %}

    {% if listLength < 2 %}
        {% set listEl = 'p' %}
    {% elif params.element is defined and params.element %}
        {% set listEl = params.element | lower %}
    {% else %}
        {% set listEl = 'ul' %}
    {% endif %}

    <{{listEl}} {% if params.id is defined and params.id %}id="{{ params.id }} "{% endif %}class="{% if listLength > 1 %}ons-list{% endif %}{% if params.classes is defined and params.classes %} {{ params.classes -}}{% endif %}{% if params.variants is defined and params.variants %}{% if params.variants is not string %}{% for variant in params.variants %} ons-list--{{ variant }}{% endfor %}{% else %} ons-list--{{ params.variants }}{% endif %}{% endif %}{% if otherClasses %} {{ otherClasses -}}{% endif %}">
        {%- for item in (params.itemsList if params.itemsList is iterable else params.itemsList.items()) -%}
            {% if listLength > 1 %}<li class="ons-list__item{% if item.listClasses is defined and item.listClasses %} {{ item.listClasses }}{% endif %}"{% if item.current is defined and item.current %} aria-current="true"{% endif %}>{% endif %}

                {% set itemText = item.text %}

                {% if params.itemsList[0] is defined and item.iconType is defined and item.iconType %}
                    {% set iconType = item.iconType if item.iconType else '' %}
                {% endif %}

                {# For Craft support we also support title and navigation title #}
                {% if item.navigationTitle is defined and item.navigationTitle %}
                    {% set itemText = item.navigationTitle %}
                {% elif item.title is defined and item.title %}
                    {% set itemText = item.title %}
                {% endif %}

                {%- if item.index is defined and item.index or item.prefix is defined and item.prefix or (params.iconPosition is defined and params.iconPosition == 'before') -%}
                    <span class="ons-list__prefix"{% if listEl != 'ol' %} aria-hidden="true"{% endif %}>
                    {%- if item.prefix is defined and item.prefix -%}
                        {{- item.prefix -}}.
                    {%- elif (item.index is defined and item.index and listEl != 'ol') or (item.index is defined and item.index and listEl == 'ol' and 'bare' in variants) -%}
                        {{- loop.index -}}.
                    {% elif params.iconPosition is defined and params.iconPosition == 'before' %}
                        {% from "components/icons/_macro.njk" import onsIcon %}
                        {{
                            onsIcon({
                                "iconType": iconType,
                                "iconSize": params.iconSize
                            })
                        }}
                    {%- endif -%}
                    </span>
                {%- endif -%}
                {%- if item.url is defined and item.url and item.current != true -%}
                    {%- if item.external is defined and item.external -%}
                        {% from "components/external-link/_macro.njk" import onsExternalLink %}
                        {{
                            onsExternalLink({
                                "url": item.url,
                                "linkText": itemText
                            })
                        }}
                    {%- else -%}
                        <a href="{{ item.url }}" class="ons-list__link {% if item.variant == 'inPageLink' %}ons-js-inpagelink {% endif %} {{ item.classes }}"{% if item.index is defined and item.index %} data-qa="list-item-{{ loop.index }}"{% endif %}{% if item.target is defined and item.target %} target="{{ item.target }}"{% endif %}{% if item.rel is defined and item.rel %} rel="{{ item.rel }}"{% endif %}>
                            {%- if item.prefix is defined and item.prefix -%}<span class="ons-u-vh">{{- item.prefix -}}</span>{%- endif -%} {{- itemText | safe -}}
                            {%- if item.target is defined and item.target == "_blank" -%}<span class="ons-u-vh">{{- item.screenreaderMessage | default("this link will open in a new tab") -}}</span>{%- endif -%}
                        </a>
                    {%- endif -%}
                {%- else -%}
                    {{- itemText | safe -}}
                {%- endif -%}
                {%- if item.suffix is defined and item.suffix or (params.iconPosition is defined and params.iconPosition == 'after') -%}
                    <span class="ons-list__suffix"{% if listEl != 'ol' %} aria-hidden="true"{% endif %}>
                    {%- if item.suffix is defined and item.suffix -%}
                        {{- item.suffix -}}
                    {%- elif (item.index is defined and item.index and listEl != 'ol') or (item.index is defined and item.index and listEl == 'ol' and 'bare' in variants) -%}
                        {{- loop.index -}}
                    {% elif params.iconPosition is defined and params.iconPosition == 'after' %}
                        {% from "components/icons/_macro.njk" import onsIcon %}
                        {{
                            onsIcon({
                                "iconType": iconType,
                                "iconSize": params.iconSize
                            })
                        }}
                    {%- endif -%} </span>
                {%- endif -%}
            {% if listLength > 1 %}</li>{%- endif -%}
        {%- endfor -%}
    </{{listEl}}>
{% endmacro %}
.ons-list {
  margin: 0 0 1rem;
  padding: 0 0 0 1.5rem;

  &__item {
    &:last-child {
      margin-bottom: 0;
    }
  }

  &--spacious {
    .ons-list__item {
      margin: 0 0 1.5rem;
    }
  }

  &--bare {
    list-style: none;
    padding-left: 0;
  }

  &--dashed {
    @extend .ons-list--bare;
    .ons-list__item {
      margin-left: 25px;
      position: relative;
      &::before {
        border-top: 1px solid $color-black;
        content: '';
        left: 0;
        margin-left: -25px;
        position: absolute;
        top: 14px;
        width: 15px;
      }
    }
  }

  &__link {
    display: inline-block;
    margin-right: 1rem;
    vertical-align: top;
    white-space: normal;
  }

  &__prefix {
    margin-right: 0.5rem;
  }

  &__suffix {
    margin-left: 0.5rem;
  }

  &__prefix,
  &__suffix {
    font-family: $font-mono;
  }

  &--prefix &,
  &--suffix &,
  &--icons & {
    &__item {
      align-items: flex-start;
      display: flex;
    }
  }

  &--social & {
    &__item {
      align-items: center;
    }
  }

  &--icons {
    margin-bottom: 0;
    .ons-list__item {
      margin-bottom: 0.5rem;
    }
  }

  &--languages {
    margin-bottom: 0;
    .ons-list__link {
      margin-right: 0;
    }
  }
}

@include bp-suffix('ons-list--inline') {
  &:not(.ons-list--icons) {
    margin: 0 1rem 0 0;
    .ons-list__item {
      display: inline-block;
      margin: 0 1rem 0 0;
      vertical-align: top;
    }
  }

  &.ons-list--icons {
    align-items: center;
    display: flex;
    flex-wrap: wrap;
  }
}

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.

<ul class="ons-list ons-list--bare">
  <li class="ons-list__item">
    <a href="#" class="ons-list__link  " target="_blank">Who we are<span class="ons-u-vh">this link will open in a new tab</span></a>
  </li>
  <li class="ons-list__item">
    <a href="#" class="ons-list__link  ">What we do</a>
  </li>
  <li class="ons-list__item">
    <a href="#" class="ons-list__link  ">Where to find us</a>
  </li>
</ul>
{% from "components/lists/_macro.njk" import onsList %}
{{
    onsList({
        "variants": 'bare',
        "itemsList": [
            {
                "url": '#',
                "text": 'Who we are',
                "target": '_blank'
            },
            {
                "url": '#',
                "text": 'What we do'
            },
            {
                "url": '#',
                "text": 'Where to find us'
            }
        ]
    })
}}
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 id for the wrapping element
classes string false Classes to be added to the wrapping element
itemsList Array<ListItem> true An array of items to show in the list
variants array or string false An array of values or single value (string) to adjust the ‘list’ display using available variants - bare, dashed, inline, social, languages
iconPosition string true Sets position of icon to before or after all the list items
iconSize string true Icon size can be set to m, l, xl, xxl
iconType string true Adds an icon to all the list items when set to the name of one of the available icons

ListItem

Name Type Required Description
text string true The text for the list item
title string false The text for the list item - only used for craft
url string false Will wrap the text in a link
listClasses string false Classes to be added to the list item
variants string false Used for variations. Available variants values: inPageLink for use with error lists when a url is also provided
rel string false allows setting of rel attribute for list item links
target string false If url is provided this will set the target for that link
screenreaderMessage string false Sets a message to be read out by screen readers when target is set to _blank and link opens in a new tab. Defaults to this link will open in a new tab if not set
index boolean false Will prefix the list item with index number if set to true
external boolean false Will style the item like an external link
prefix string true Will prefix the list item with whatever prefix is set to
suffix string true Will suffix the list item with whatever suffix is set to
iconType string true Adds an icon to the list item when set to the name of one of the available icons
{% macro onsList(params) %}
    {% set variants = params.variants if params.variants else '' %}
    {% set listLength = params.itemsList | length %}

    {% if params.itemsList[0] is defined and params.itemsList[0].prefix %}
        {% set otherClasses = 'ons-list--bare ons-list--prefix' %}
    {% elif params.itemsList[0] is defined and params.itemsList[0].suffix %}
        {% set otherClasses = 'ons-list--bare ons-list--suffix' %}
    {% elif params.itemsList[0] is defined and params.iconPosition is defined and params.iconPosition %}
        {% set otherClasses = 'ons-list--bare ons-list--icons' %}
        {% set iconType = params.iconType if params.iconType else '' %}
    {% else %}
        {% set otherClasses = '' %}
    {% endif %}

    {% if listLength < 2 %}
        {% set listEl = 'p' %}
    {% elif params.element is defined and params.element %}
        {% set listEl = params.element | lower %}
    {% else %}
        {% set listEl = 'ul' %}
    {% endif %}

    <{{listEl}} {% if params.id is defined and params.id %}id="{{ params.id }} "{% endif %}class="{% if listLength > 1 %}ons-list{% endif %}{% if params.classes is defined and params.classes %} {{ params.classes -}}{% endif %}{% if params.variants is defined and params.variants %}{% if params.variants is not string %}{% for variant in params.variants %} ons-list--{{ variant }}{% endfor %}{% else %} ons-list--{{ params.variants }}{% endif %}{% endif %}{% if otherClasses %} {{ otherClasses -}}{% endif %}">
        {%- for item in (params.itemsList if params.itemsList is iterable else params.itemsList.items()) -%}
            {% if listLength > 1 %}<li class="ons-list__item{% if item.listClasses is defined and item.listClasses %} {{ item.listClasses }}{% endif %}"{% if item.current is defined and item.current %} aria-current="true"{% endif %}>{% endif %}

                {% set itemText = item.text %}

                {% if params.itemsList[0] is defined and item.iconType is defined and item.iconType %}
                    {% set iconType = item.iconType if item.iconType else '' %}
                {% endif %}

                {# For Craft support we also support title and navigation title #}
                {% if item.navigationTitle is defined and item.navigationTitle %}
                    {% set itemText = item.navigationTitle %}
                {% elif item.title is defined and item.title %}
                    {% set itemText = item.title %}
                {% endif %}

                {%- if item.index is defined and item.index or item.prefix is defined and item.prefix or (params.iconPosition is defined and params.iconPosition == 'before') -%}
                    <span class="ons-list__prefix"{% if listEl != 'ol' %} aria-hidden="true"{% endif %}>
                    {%- if item.prefix is defined and item.prefix -%}
                        {{- item.prefix -}}.
                    {%- elif (item.index is defined and item.index and listEl != 'ol') or (item.index is defined and item.index and listEl == 'ol' and 'bare' in variants) -%}
                        {{- loop.index -}}.
                    {% elif params.iconPosition is defined and params.iconPosition == 'before' %}
                        {% from "components/icons/_macro.njk" import onsIcon %}
                        {{
                            onsIcon({
                                "iconType": iconType,
                                "iconSize": params.iconSize
                            })
                        }}
                    {%- endif -%}
                    </span>
                {%- endif -%}
                {%- if item.url is defined and item.url and item.current != true -%}
                    {%- if item.external is defined and item.external -%}
                        {% from "components/external-link/_macro.njk" import onsExternalLink %}
                        {{
                            onsExternalLink({
                                "url": item.url,
                                "linkText": itemText
                            })
                        }}
                    {%- else -%}
                        <a href="{{ item.url }}" class="ons-list__link {% if item.variant == 'inPageLink' %}ons-js-inpagelink {% endif %} {{ item.classes }}"{% if item.index is defined and item.index %} data-qa="list-item-{{ loop.index }}"{% endif %}{% if item.target is defined and item.target %} target="{{ item.target }}"{% endif %}{% if item.rel is defined and item.rel %} rel="{{ item.rel }}"{% endif %}>
                            {%- if item.prefix is defined and item.prefix -%}<span class="ons-u-vh">{{- item.prefix -}}</span>{%- endif -%} {{- itemText | safe -}}
                            {%- if item.target is defined and item.target == "_blank" -%}<span class="ons-u-vh">{{- item.screenreaderMessage | default("this link will open in a new tab") -}}</span>{%- endif -%}
                        </a>
                    {%- endif -%}
                {%- else -%}
                    {{- itemText | safe -}}
                {%- endif -%}
                {%- if item.suffix is defined and item.suffix or (params.iconPosition is defined and params.iconPosition == 'after') -%}
                    <span class="ons-list__suffix"{% if listEl != 'ol' %} aria-hidden="true"{% endif %}>
                    {%- if item.suffix is defined and item.suffix -%}
                        {{- item.suffix -}}
                    {%- elif (item.index is defined and item.index and listEl != 'ol') or (item.index is defined and item.index and listEl == 'ol' and 'bare' in variants) -%}
                        {{- loop.index -}}
                    {% elif params.iconPosition is defined and params.iconPosition == 'after' %}
                        {% from "components/icons/_macro.njk" import onsIcon %}
                        {{
                            onsIcon({
                                "iconType": iconType,
                                "iconSize": params.iconSize
                            })
                        }}
                    {%- endif -%} </span>
                {%- endif -%}
            {% if listLength > 1 %}</li>{%- endif -%}
        {%- endfor -%}
    </{{listEl}}>
{% endmacro %}
.ons-list {
  margin: 0 0 1rem;
  padding: 0 0 0 1.5rem;

  &__item {
    &:last-child {
      margin-bottom: 0;
    }
  }

  &--spacious {
    .ons-list__item {
      margin: 0 0 1.5rem;
    }
  }

  &--bare {
    list-style: none;
    padding-left: 0;
  }

  &--dashed {
    @extend .ons-list--bare;
    .ons-list__item {
      margin-left: 25px;
      position: relative;
      &::before {
        border-top: 1px solid $color-black;
        content: '';
        left: 0;
        margin-left: -25px;
        position: absolute;
        top: 14px;
        width: 15px;
      }
    }
  }

  &__link {
    display: inline-block;
    margin-right: 1rem;
    vertical-align: top;
    white-space: normal;
  }

  &__prefix {
    margin-right: 0.5rem;
  }

  &__suffix {
    margin-left: 0.5rem;
  }

  &__prefix,
  &__suffix {
    font-family: $font-mono;
  }

  &--prefix &,
  &--suffix &,
  &--icons & {
    &__item {
      align-items: flex-start;
      display: flex;
    }
  }

  &--social & {
    &__item {
      align-items: center;
    }
  }

  &--icons {
    margin-bottom: 0;
    .ons-list__item {
      margin-bottom: 0.5rem;
    }
  }

  &--languages {
    margin-bottom: 0;
    .ons-list__link {
      margin-right: 0;
    }
  }
}

@include bp-suffix('ons-list--inline') {
  &:not(.ons-list--icons) {
    margin: 0 1rem 0 0;
    .ons-list__item {
      display: inline-block;
      margin: 0 1rem 0 0;
      vertical-align: top;
    }
  }

  &.ons-list--icons {
    align-items: center;
    display: flex;
    flex-wrap: wrap;
  }
}

Dashed list

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

<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>
{% from "components/lists/_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?'
            }
        ]
    })
}}
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 id for the wrapping element
classes string false Classes to be added to the wrapping element
itemsList Array<ListItem> true An array of items to show in the list
variants array or string false An array of values or single value (string) to adjust the ‘list’ display using available variants - bare, dashed, inline, social, languages
iconPosition string true Sets position of icon to before or after all the list items
iconSize string true Icon size can be set to m, l, xl, xxl
iconType string true Adds an icon to all the list items when set to the name of one of the available icons

ListItem

Name Type Required Description
text string true The text for the list item
title string false The text for the list item - only used for craft
url string false Will wrap the text in a link
listClasses string false Classes to be added to the list item
variants string false Used for variations. Available variants values: inPageLink for use with error lists when a url is also provided
rel string false allows setting of rel attribute for list item links
target string false If url is provided this will set the target for that link
screenreaderMessage string false Sets a message to be read out by screen readers when target is set to _blank and link opens in a new tab. Defaults to this link will open in a new tab if not set
index boolean false Will prefix the list item with index number if set to true
external boolean false Will style the item like an external link
prefix string true Will prefix the list item with whatever prefix is set to
suffix string true Will suffix the list item with whatever suffix is set to
iconType string true Adds an icon to the list item when set to the name of one of the available icons
{% macro onsList(params) %}
    {% set variants = params.variants if params.variants else '' %}
    {% set listLength = params.itemsList | length %}

    {% if params.itemsList[0] is defined and params.itemsList[0].prefix %}
        {% set otherClasses = 'ons-list--bare ons-list--prefix' %}
    {% elif params.itemsList[0] is defined and params.itemsList[0].suffix %}
        {% set otherClasses = 'ons-list--bare ons-list--suffix' %}
    {% elif params.itemsList[0] is defined and params.iconPosition is defined and params.iconPosition %}
        {% set otherClasses = 'ons-list--bare ons-list--icons' %}
        {% set iconType = params.iconType if params.iconType else '' %}
    {% else %}
        {% set otherClasses = '' %}
    {% endif %}

    {% if listLength < 2 %}
        {% set listEl = 'p' %}
    {% elif params.element is defined and params.element %}
        {% set listEl = params.element | lower %}
    {% else %}
        {% set listEl = 'ul' %}
    {% endif %}

    <{{listEl}} {% if params.id is defined and params.id %}id="{{ params.id }} "{% endif %}class="{% if listLength > 1 %}ons-list{% endif %}{% if params.classes is defined and params.classes %} {{ params.classes -}}{% endif %}{% if params.variants is defined and params.variants %}{% if params.variants is not string %}{% for variant in params.variants %} ons-list--{{ variant }}{% endfor %}{% else %} ons-list--{{ params.variants }}{% endif %}{% endif %}{% if otherClasses %} {{ otherClasses -}}{% endif %}">
        {%- for item in (params.itemsList if params.itemsList is iterable else params.itemsList.items()) -%}
            {% if listLength > 1 %}<li class="ons-list__item{% if item.listClasses is defined and item.listClasses %} {{ item.listClasses }}{% endif %}"{% if item.current is defined and item.current %} aria-current="true"{% endif %}>{% endif %}

                {% set itemText = item.text %}

                {% if params.itemsList[0] is defined and item.iconType is defined and item.iconType %}
                    {% set iconType = item.iconType if item.iconType else '' %}
                {% endif %}

                {# For Craft support we also support title and navigation title #}
                {% if item.navigationTitle is defined and item.navigationTitle %}
                    {% set itemText = item.navigationTitle %}
                {% elif item.title is defined and item.title %}
                    {% set itemText = item.title %}
                {% endif %}

                {%- if item.index is defined and item.index or item.prefix is defined and item.prefix or (params.iconPosition is defined and params.iconPosition == 'before') -%}
                    <span class="ons-list__prefix"{% if listEl != 'ol' %} aria-hidden="true"{% endif %}>
                    {%- if item.prefix is defined and item.prefix -%}
                        {{- item.prefix -}}.
                    {%- elif (item.index is defined and item.index and listEl != 'ol') or (item.index is defined and item.index and listEl == 'ol' and 'bare' in variants) -%}
                        {{- loop.index -}}.
                    {% elif params.iconPosition is defined and params.iconPosition == 'before' %}
                        {% from "components/icons/_macro.njk" import onsIcon %}
                        {{
                            onsIcon({
                                "iconType": iconType,
                                "iconSize": params.iconSize
                            })
                        }}
                    {%- endif -%}
                    </span>
                {%- endif -%}
                {%- if item.url is defined and item.url and item.current != true -%}
                    {%- if item.external is defined and item.external -%}
                        {% from "components/external-link/_macro.njk" import onsExternalLink %}
                        {{
                            onsExternalLink({
                                "url": item.url,
                                "linkText": itemText
                            })
                        }}
                    {%- else -%}
                        <a href="{{ item.url }}" class="ons-list__link {% if item.variant == 'inPageLink' %}ons-js-inpagelink {% endif %} {{ item.classes }}"{% if item.index is defined and item.index %} data-qa="list-item-{{ loop.index }}"{% endif %}{% if item.target is defined and item.target %} target="{{ item.target }}"{% endif %}{% if item.rel is defined and item.rel %} rel="{{ item.rel }}"{% endif %}>
                            {%- if item.prefix is defined and item.prefix -%}<span class="ons-u-vh">{{- item.prefix -}}</span>{%- endif -%} {{- itemText | safe -}}
                            {%- if item.target is defined and item.target == "_blank" -%}<span class="ons-u-vh">{{- item.screenreaderMessage | default("this link will open in a new tab") -}}</span>{%- endif -%}
                        </a>
                    {%- endif -%}
                {%- else -%}
                    {{- itemText | safe -}}
                {%- endif -%}
                {%- if item.suffix is defined and item.suffix or (params.iconPosition is defined and params.iconPosition == 'after') -%}
                    <span class="ons-list__suffix"{% if listEl != 'ol' %} aria-hidden="true"{% endif %}>
                    {%- if item.suffix is defined and item.suffix -%}
                        {{- item.suffix -}}
                    {%- elif (item.index is defined and item.index and listEl != 'ol') or (item.index is defined and item.index and listEl == 'ol' and 'bare' in variants) -%}
                        {{- loop.index -}}
                    {% elif params.iconPosition is defined and params.iconPosition == 'after' %}
                        {% from "components/icons/_macro.njk" import onsIcon %}
                        {{
                            onsIcon({
                                "iconType": iconType,
                                "iconSize": params.iconSize
                            })
                        }}
                    {%- endif -%} </span>
                {%- endif -%}
            {% if listLength > 1 %}</li>{%- endif -%}
        {%- endfor -%}
    </{{listEl}}>
{% endmacro %}
.ons-list {
  margin: 0 0 1rem;
  padding: 0 0 0 1.5rem;

  &__item {
    &:last-child {
      margin-bottom: 0;
    }
  }

  &--spacious {
    .ons-list__item {
      margin: 0 0 1.5rem;
    }
  }

  &--bare {
    list-style: none;
    padding-left: 0;
  }

  &--dashed {
    @extend .ons-list--bare;
    .ons-list__item {
      margin-left: 25px;
      position: relative;
      &::before {
        border-top: 1px solid $color-black;
        content: '';
        left: 0;
        margin-left: -25px;
        position: absolute;
        top: 14px;
        width: 15px;
      }
    }
  }

  &__link {
    display: inline-block;
    margin-right: 1rem;
    vertical-align: top;
    white-space: normal;
  }

  &__prefix {
    margin-right: 0.5rem;
  }

  &__suffix {
    margin-left: 0.5rem;
  }

  &__prefix,
  &__suffix {
    font-family: $font-mono;
  }

  &--prefix &,
  &--suffix &,
  &--icons & {
    &__item {
      align-items: flex-start;
      display: flex;
    }
  }

  &--social & {
    &__item {
      align-items: center;
    }
  }

  &--icons {
    margin-bottom: 0;
    .ons-list__item {
      margin-bottom: 0.5rem;
    }
  }

  &--languages {
    margin-bottom: 0;
    .ons-list__link {
      margin-right: 0;
    }
  }
}

@include bp-suffix('ons-list--inline') {
  &:not(.ons-list--icons) {
    margin: 0 1rem 0 0;
    .ons-list__item {
      display: inline-block;
      margin: 0 1rem 0 0;
      vertical-align: top;
    }
  }

  &.ons-list--icons {
    align-items: center;
    display: flex;
    flex-wrap: wrap;
  }
}

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.

<ul class="ons-list ons-list--bare 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>
{% from "components/lists/_macro.njk" import onsList %}
{{
    onsList({
        "itemsList": [
            {
                "text": 'birth certificate',
                "prefix": 'H1'
            },
            {
                "text": 'national insurance number',
                "prefix": 'H2'
            },
            {
                "text": 'passport',
                "prefix": 'H3'
            }
        ]
    })
}}
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 id for the wrapping element
classes string false Classes to be added to the wrapping element
itemsList Array<ListItem> true An array of items to show in the list
variants array or string false An array of values or single value (string) to adjust the ‘list’ display using available variants - bare, dashed, inline, social, languages
iconPosition string true Sets position of icon to before or after all the list items
iconSize string true Icon size can be set to m, l, xl, xxl
iconType string true Adds an icon to all the list items when set to the name of one of the available icons

ListItem

Name Type Required Description
text string true The text for the list item
title string false The text for the list item - only used for craft
url string false Will wrap the text in a link
listClasses string false Classes to be added to the list item
variants string false Used for variations. Available variants values: inPageLink for use with error lists when a url is also provided
rel string false allows setting of rel attribute for list item links
target string false If url is provided this will set the target for that link
screenreaderMessage string false Sets a message to be read out by screen readers when target is set to _blank and link opens in a new tab. Defaults to this link will open in a new tab if not set
index boolean false Will prefix the list item with index number if set to true
external boolean false Will style the item like an external link
prefix string true Will prefix the list item with whatever prefix is set to
suffix string true Will suffix the list item with whatever suffix is set to
iconType string true Adds an icon to the list item when set to the name of one of the available icons
{% macro onsList(params) %}
    {% set variants = params.variants if params.variants else '' %}
    {% set listLength = params.itemsList | length %}

    {% if params.itemsList[0] is defined and params.itemsList[0].prefix %}
        {% set otherClasses = 'ons-list--bare ons-list--prefix' %}
    {% elif params.itemsList[0] is defined and params.itemsList[0].suffix %}
        {% set otherClasses = 'ons-list--bare ons-list--suffix' %}
    {% elif params.itemsList[0] is defined and params.iconPosition is defined and params.iconPosition %}
        {% set otherClasses = 'ons-list--bare ons-list--icons' %}
        {% set iconType = params.iconType if params.iconType else '' %}
    {% else %}
        {% set otherClasses = '' %}
    {% endif %}

    {% if listLength < 2 %}
        {% set listEl = 'p' %}
    {% elif params.element is defined and params.element %}
        {% set listEl = params.element | lower %}
    {% else %}
        {% set listEl = 'ul' %}
    {% endif %}

    <{{listEl}} {% if params.id is defined and params.id %}id="{{ params.id }} "{% endif %}class="{% if listLength > 1 %}ons-list{% endif %}{% if params.classes is defined and params.classes %} {{ params.classes -}}{% endif %}{% if params.variants is defined and params.variants %}{% if params.variants is not string %}{% for variant in params.variants %} ons-list--{{ variant }}{% endfor %}{% else %} ons-list--{{ params.variants }}{% endif %}{% endif %}{% if otherClasses %} {{ otherClasses -}}{% endif %}">
        {%- for item in (params.itemsList if params.itemsList is iterable else params.itemsList.items()) -%}
            {% if listLength > 1 %}<li class="ons-list__item{% if item.listClasses is defined and item.listClasses %} {{ item.listClasses }}{% endif %}"{% if item.current is defined and item.current %} aria-current="true"{% endif %}>{% endif %}

                {% set itemText = item.text %}

                {% if params.itemsList[0] is defined and item.iconType is defined and item.iconType %}
                    {% set iconType = item.iconType if item.iconType else '' %}
                {% endif %}

                {# For Craft support we also support title and navigation title #}
                {% if item.navigationTitle is defined and item.navigationTitle %}
                    {% set itemText = item.navigationTitle %}
                {% elif item.title is defined and item.title %}
                    {% set itemText = item.title %}
                {% endif %}

                {%- if item.index is defined and item.index or item.prefix is defined and item.prefix or (params.iconPosition is defined and params.iconPosition == 'before') -%}
                    <span class="ons-list__prefix"{% if listEl != 'ol' %} aria-hidden="true"{% endif %}>
                    {%- if item.prefix is defined and item.prefix -%}
                        {{- item.prefix -}}.
                    {%- elif (item.index is defined and item.index and listEl != 'ol') or (item.index is defined and item.index and listEl == 'ol' and 'bare' in variants) -%}
                        {{- loop.index -}}.
                    {% elif params.iconPosition is defined and params.iconPosition == 'before' %}
                        {% from "components/icons/_macro.njk" import onsIcon %}
                        {{
                            onsIcon({
                                "iconType": iconType,
                                "iconSize": params.iconSize
                            })
                        }}
                    {%- endif -%}
                    </span>
                {%- endif -%}
                {%- if item.url is defined and item.url and item.current != true -%}
                    {%- if item.external is defined and item.external -%}
                        {% from "components/external-link/_macro.njk" import onsExternalLink %}
                        {{
                            onsExternalLink({
                                "url": item.url,
                                "linkText": itemText
                            })
                        }}
                    {%- else -%}
                        <a href="{{ item.url }}" class="ons-list__link {% if item.variant == 'inPageLink' %}ons-js-inpagelink {% endif %} {{ item.classes }}"{% if item.index is defined and item.index %} data-qa="list-item-{{ loop.index }}"{% endif %}{% if item.target is defined and item.target %} target="{{ item.target }}"{% endif %}{% if item.rel is defined and item.rel %} rel="{{ item.rel }}"{% endif %}>
                            {%- if item.prefix is defined and item.prefix -%}<span class="ons-u-vh">{{- item.prefix -}}</span>{%- endif -%} {{- itemText | safe -}}
                            {%- if item.target is defined and item.target == "_blank" -%}<span class="ons-u-vh">{{- item.screenreaderMessage | default("this link will open in a new tab") -}}</span>{%- endif -%}
                        </a>
                    {%- endif -%}
                {%- else -%}
                    {{- itemText | safe -}}
                {%- endif -%}
                {%- if item.suffix is defined and item.suffix or (params.iconPosition is defined and params.iconPosition == 'after') -%}
                    <span class="ons-list__suffix"{% if listEl != 'ol' %} aria-hidden="true"{% endif %}>
                    {%- if item.suffix is defined and item.suffix -%}
                        {{- item.suffix -}}
                    {%- elif (item.index is defined and item.index and listEl != 'ol') or (item.index is defined and item.index and listEl == 'ol' and 'bare' in variants) -%}
                        {{- loop.index -}}
                    {% elif params.iconPosition is defined and params.iconPosition == 'after' %}
                        {% from "components/icons/_macro.njk" import onsIcon %}
                        {{
                            onsIcon({
                                "iconType": iconType,
                                "iconSize": params.iconSize
                            })
                        }}
                    {%- endif -%} </span>
                {%- endif -%}
            {% if listLength > 1 %}</li>{%- endif -%}
        {%- endfor -%}
    </{{listEl}}>
{% endmacro %}
.ons-list {
  margin: 0 0 1rem;
  padding: 0 0 0 1.5rem;

  &__item {
    &:last-child {
      margin-bottom: 0;
    }
  }

  &--spacious {
    .ons-list__item {
      margin: 0 0 1.5rem;
    }
  }

  &--bare {
    list-style: none;
    padding-left: 0;
  }

  &--dashed {
    @extend .ons-list--bare;
    .ons-list__item {
      margin-left: 25px;
      position: relative;
      &::before {
        border-top: 1px solid $color-black;
        content: '';
        left: 0;
        margin-left: -25px;
        position: absolute;
        top: 14px;
        width: 15px;
      }
    }
  }

  &__link {
    display: inline-block;
    margin-right: 1rem;
    vertical-align: top;
    white-space: normal;
  }

  &__prefix {
    margin-right: 0.5rem;
  }

  &__suffix {
    margin-left: 0.5rem;
  }

  &__prefix,
  &__suffix {
    font-family: $font-mono;
  }

  &--prefix &,
  &--suffix &,
  &--icons & {
    &__item {
      align-items: flex-start;
      display: flex;
    }
  }

  &--social & {
    &__item {
      align-items: center;
    }
  }

  &--icons {
    margin-bottom: 0;
    .ons-list__item {
      margin-bottom: 0.5rem;
    }
  }

  &--languages {
    margin-bottom: 0;
    .ons-list__link {
      margin-right: 0;
    }
  }
}

@include bp-suffix('ons-list--inline') {
  &:not(.ons-list--icons) {
    margin: 0 1rem 0 0;
    .ons-list__item {
      display: inline-block;
      margin: 0 1rem 0 0;
      vertical-align: top;
    }
  }

  &.ons-list--icons {
    align-items: center;
    display: flex;
    flex-wrap: wrap;
  }
}

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.

<ul class="ons-list ons-list--bare 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>
{% from "components/lists/_macro.njk" import onsList %}
{{
    onsList({
        "itemsList": [
            {
                "text": 'birth certificate',
                "suffix": 'A'
            },
            {
                "text": 'national insurance number',
                "suffix": 'B'
            },
            {
                "text": 'passport',
                "suffix": 'C'
            }
        ]
    })
}}
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 id for the wrapping element
classes string false Classes to be added to the wrapping element
itemsList Array<ListItem> true An array of items to show in the list
variants array or string false An array of values or single value (string) to adjust the ‘list’ display using available variants - bare, dashed, inline, social, languages
iconPosition string true Sets position of icon to before or after all the list items
iconSize string true Icon size can be set to m, l, xl, xxl
iconType string true Adds an icon to all the list items when set to the name of one of the available icons

ListItem

Name Type Required Description
text string true The text for the list item
title string false The text for the list item - only used for craft
url string false Will wrap the text in a link
listClasses string false Classes to be added to the list item
variants string false Used for variations. Available variants values: inPageLink for use with error lists when a url is also provided
rel string false allows setting of rel attribute for list item links
target string false If url is provided this will set the target for that link
screenreaderMessage string false Sets a message to be read out by screen readers when target is set to _blank and link opens in a new tab. Defaults to this link will open in a new tab if not set
index boolean false Will prefix the list item with index number if set to true
external boolean false Will style the item like an external link
prefix string true Will prefix the list item with whatever prefix is set to
suffix string true Will suffix the list item with whatever suffix is set to
iconType string true Adds an icon to the list item when set to the name of one of the available icons
{% macro onsList(params) %}
    {% set variants = params.variants if params.variants else '' %}
    {% set listLength = params.itemsList | length %}

    {% if params.itemsList[0] is defined and params.itemsList[0].prefix %}
        {% set otherClasses = 'ons-list--bare ons-list--prefix' %}
    {% elif params.itemsList[0] is defined and params.itemsList[0].suffix %}
        {% set otherClasses = 'ons-list--bare ons-list--suffix' %}
    {% elif params.itemsList[0] is defined and params.iconPosition is defined and params.iconPosition %}
        {% set otherClasses = 'ons-list--bare ons-list--icons' %}
        {% set iconType = params.iconType if params.iconType else '' %}
    {% else %}
        {% set otherClasses = '' %}
    {% endif %}

    {% if listLength < 2 %}
        {% set listEl = 'p' %}
    {% elif params.element is defined and params.element %}
        {% set listEl = params.element | lower %}
    {% else %}
        {% set listEl = 'ul' %}
    {% endif %}

    <{{listEl}} {% if params.id is defined and params.id %}id="{{ params.id }} "{% endif %}class="{% if listLength > 1 %}ons-list{% endif %}{% if params.classes is defined and params.classes %} {{ params.classes -}}{% endif %}{% if params.variants is defined and params.variants %}{% if params.variants is not string %}{% for variant in params.variants %} ons-list--{{ variant }}{% endfor %}{% else %} ons-list--{{ params.variants }}{% endif %}{% endif %}{% if otherClasses %} {{ otherClasses -}}{% endif %}">
        {%- for item in (params.itemsList if params.itemsList is iterable else params.itemsList.items()) -%}
            {% if listLength > 1 %}<li class="ons-list__item{% if item.listClasses is defined and item.listClasses %} {{ item.listClasses }}{% endif %}"{% if item.current is defined and item.current %} aria-current="true"{% endif %}>{% endif %}

                {% set itemText = item.text %}

                {% if params.itemsList[0] is defined and item.iconType is defined and item.iconType %}
                    {% set iconType = item.iconType if item.iconType else '' %}
                {% endif %}

                {# For Craft support we also support title and navigation title #}
                {% if item.navigationTitle is defined and item.navigationTitle %}
                    {% set itemText = item.navigationTitle %}
                {% elif item.title is defined and item.title %}
                    {% set itemText = item.title %}
                {% endif %}

                {%- if item.index is defined and item.index or item.prefix is defined and item.prefix or (params.iconPosition is defined and params.iconPosition == 'before') -%}
                    <span class="ons-list__prefix"{% if listEl != 'ol' %} aria-hidden="true"{% endif %}>
                    {%- if item.prefix is defined and item.prefix -%}
                        {{- item.prefix -}}.
                    {%- elif (item.index is defined and item.index and listEl != 'ol') or (item.index is defined and item.index and listEl == 'ol' and 'bare' in variants) -%}
                        {{- loop.index -}}.
                    {% elif params.iconPosition is defined and params.iconPosition == 'before' %}
                        {% from "components/icons/_macro.njk" import onsIcon %}
                        {{
                            onsIcon({
                                "iconType": iconType,
                                "iconSize": params.iconSize
                            })
                        }}
                    {%- endif -%}
                    </span>
                {%- endif -%}
                {%- if item.url is defined and item.url and item.current != true -%}
                    {%- if item.external is defined and item.external -%}
                        {% from "components/external-link/_macro.njk" import onsExternalLink %}
                        {{
                            onsExternalLink({
                                "url": item.url,
                                "linkText": itemText
                            })
                        }}
                    {%- else -%}
                        <a href="{{ item.url }}" class="ons-list__link {% if item.variant == 'inPageLink' %}ons-js-inpagelink {% endif %} {{ item.classes }}"{% if item.index is defined and item.index %} data-qa="list-item-{{ loop.index }}"{% endif %}{% if item.target is defined and item.target %} target="{{ item.target }}"{% endif %}{% if item.rel is defined and item.rel %} rel="{{ item.rel }}"{% endif %}>
                            {%- if item.prefix is defined and item.prefix -%}<span class="ons-u-vh">{{- item.prefix -}}</span>{%- endif -%} {{- itemText | safe -}}
                            {%- if item.target is defined and item.target == "_blank" -%}<span class="ons-u-vh">{{- item.screenreaderMessage | default("this link will open in a new tab") -}}</span>{%- endif -%}
                        </a>
                    {%- endif -%}
                {%- else -%}
                    {{- itemText | safe -}}
                {%- endif -%}
                {%- if item.suffix is defined and item.suffix or (params.iconPosition is defined and params.iconPosition == 'after') -%}
                    <span class="ons-list__suffix"{% if listEl != 'ol' %} aria-hidden="true"{% endif %}>
                    {%- if item.suffix is defined and item.suffix -%}
                        {{- item.suffix -}}
                    {%- elif (item.index is defined and item.index and listEl != 'ol') or (item.index is defined and item.index and listEl == 'ol' and 'bare' in variants) -%}
                        {{- loop.index -}}
                    {% elif params.iconPosition is defined and params.iconPosition == 'after' %}
                        {% from "components/icons/_macro.njk" import onsIcon %}
                        {{
                            onsIcon({
                                "iconType": iconType,
                                "iconSize": params.iconSize
                            })
                        }}
                    {%- endif -%} </span>
                {%- endif -%}
            {% if listLength > 1 %}</li>{%- endif -%}
        {%- endfor -%}
    </{{listEl}}>
{% endmacro %}
.ons-list {
  margin: 0 0 1rem;
  padding: 0 0 0 1.5rem;

  &__item {
    &:last-child {
      margin-bottom: 0;
    }
  }

  &--spacious {
    .ons-list__item {
      margin: 0 0 1.5rem;
    }
  }

  &--bare {
    list-style: none;
    padding-left: 0;
  }

  &--dashed {
    @extend .ons-list--bare;
    .ons-list__item {
      margin-left: 25px;
      position: relative;
      &::before {
        border-top: 1px solid $color-black;
        content: '';
        left: 0;
        margin-left: -25px;
        position: absolute;
        top: 14px;
        width: 15px;
      }
    }
  }

  &__link {
    display: inline-block;
    margin-right: 1rem;
    vertical-align: top;
    white-space: normal;
  }

  &__prefix {
    margin-right: 0.5rem;
  }

  &__suffix {
    margin-left: 0.5rem;
  }

  &__prefix,
  &__suffix {
    font-family: $font-mono;
  }

  &--prefix &,
  &--suffix &,
  &--icons & {
    &__item {
      align-items: flex-start;
      display: flex;
    }
  }

  &--social & {
    &__item {
      align-items: center;
    }
  }

  &--icons {
    margin-bottom: 0;
    .ons-list__item {
      margin-bottom: 0.5rem;
    }
  }

  &--languages {
    margin-bottom: 0;
    .ons-list__link {
      margin-right: 0;
    }
  }
}

@include bp-suffix('ons-list--inline') {
  &:not(.ons-list--icons) {
    margin: 0 1rem 0 0;
    .ons-list__item {
      display: inline-block;
      margin: 0 1rem 0 0;
      vertical-align: top;
    }
  }

  &.ons-list--icons {
    align-items: center;
    display: flex;
    flex-wrap: wrap;
  }
}

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.

<ul class="ons-list ons-list--bare ons-list--inline">
  <li class="ons-list__item">
    <a href="#" class="ons-list__link  ">Contact us</a>
  </li>
  <li class="ons-list__item">
    <a href="#" class="ons-list__link  ">Cookies and privacy</a>
  </li>
  <li class="ons-list__item">
    <a href="#" class="ons-list__link  ">Terms and conditions</a>
  </li>
</ul>
{% from "components/lists/_macro.njk" import onsList %}
{{
    onsList({
        "variants": ['bare', 'inline'],
        "itemsList": [
            {
                "text": 'Contact us',
                "url": '#'
            },
            {
                "text": 'Cookies and privacy',
                "url": '#'
            },
            {
                "text": 'Terms and conditions',
                "url": '#'
            }
        ]
    })
}}
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 id for the wrapping element
classes string false Classes to be added to the wrapping element
itemsList Array<ListItem> true An array of items to show in the list
variants array or string false An array of values or single value (string) to adjust the ‘list’ display using available variants - bare, dashed, inline, social, languages
iconPosition string true Sets position of icon to before or after all the list items
iconSize string true Icon size can be set to m, l, xl, xxl
iconType string true Adds an icon to all the list items when set to the name of one of the available icons

ListItem

Name Type Required Description
text string true The text for the list item
title string false The text for the list item - only used for craft
url string false Will wrap the text in a link
listClasses string false Classes to be added to the list item
variants string false Used for variations. Available variants values: inPageLink for use with error lists when a url is also provided
rel string false allows setting of rel attribute for list item links
target string false If url is provided this will set the target for that link
screenreaderMessage string false Sets a message to be read out by screen readers when target is set to _blank and link opens in a new tab. Defaults to this link will open in a new tab if not set
index boolean false Will prefix the list item with index number if set to true
external boolean false Will style the item like an external link
prefix string true Will prefix the list item with whatever prefix is set to
suffix string true Will suffix the list item with whatever suffix is set to
iconType string true Adds an icon to the list item when set to the name of one of the available icons
{% macro onsList(params) %}
    {% set variants = params.variants if params.variants else '' %}
    {% set listLength = params.itemsList | length %}

    {% if params.itemsList[0] is defined and params.itemsList[0].prefix %}
        {% set otherClasses = 'ons-list--bare ons-list--prefix' %}
    {% elif params.itemsList[0] is defined and params.itemsList[0].suffix %}
        {% set otherClasses = 'ons-list--bare ons-list--suffix' %}
    {% elif params.itemsList[0] is defined and params.iconPosition is defined and params.iconPosition %}
        {% set otherClasses = 'ons-list--bare ons-list--icons' %}
        {% set iconType = params.iconType if params.iconType else '' %}
    {% else %}
        {% set otherClasses = '' %}
    {% endif %}

    {% if listLength < 2 %}
        {% set listEl = 'p' %}
    {% elif params.element is defined and params.element %}
        {% set listEl = params.element | lower %}
    {% else %}
        {% set listEl = 'ul' %}
    {% endif %}

    <{{listEl}} {% if params.id is defined and params.id %}id="{{ params.id }} "{% endif %}class="{% if listLength > 1 %}ons-list{% endif %}{% if params.classes is defined and params.classes %} {{ params.classes -}}{% endif %}{% if params.variants is defined and params.variants %}{% if params.variants is not string %}{% for variant in params.variants %} ons-list--{{ variant }}{% endfor %}{% else %} ons-list--{{ params.variants }}{% endif %}{% endif %}{% if otherClasses %} {{ otherClasses -}}{% endif %}">
        {%- for item in (params.itemsList if params.itemsList is iterable else params.itemsList.items()) -%}
            {% if listLength > 1 %}<li class="ons-list__item{% if item.listClasses is defined and item.listClasses %} {{ item.listClasses }}{% endif %}"{% if item.current is defined and item.current %} aria-current="true"{% endif %}>{% endif %}

                {% set itemText = item.text %}

                {% if params.itemsList[0] is defined and item.iconType is defined and item.iconType %}
                    {% set iconType = item.iconType if item.iconType else '' %}
                {% endif %}

                {# For Craft support we also support title and navigation title #}
                {% if item.navigationTitle is defined and item.navigationTitle %}
                    {% set itemText = item.navigationTitle %}
                {% elif item.title is defined and item.title %}
                    {% set itemText = item.title %}
                {% endif %}

                {%- if item.index is defined and item.index or item.prefix is defined and item.prefix or (params.iconPosition is defined and params.iconPosition == 'before') -%}
                    <span class="ons-list__prefix"{% if listEl != 'ol' %} aria-hidden="true"{% endif %}>
                    {%- if item.prefix is defined and item.prefix -%}
                        {{- item.prefix -}}.
                    {%- elif (item.index is defined and item.index and listEl != 'ol') or (item.index is defined and item.index and listEl == 'ol' and 'bare' in variants) -%}
                        {{- loop.index -}}.
                    {% elif params.iconPosition is defined and params.iconPosition == 'before' %}
                        {% from "components/icons/_macro.njk" import onsIcon %}
                        {{
                            onsIcon({
                                "iconType": iconType,
                                "iconSize": params.iconSize
                            })
                        }}
                    {%- endif -%}
                    </span>
                {%- endif -%}
                {%- if item.url is defined and item.url and item.current != true -%}
                    {%- if item.external is defined and item.external -%}
                        {% from "components/external-link/_macro.njk" import onsExternalLink %}
                        {{
                            onsExternalLink({
                                "url": item.url,
                                "linkText": itemText
                            })
                        }}
                    {%- else -%}
                        <a href="{{ item.url }}" class="ons-list__link {% if item.variant == 'inPageLink' %}ons-js-inpagelink {% endif %} {{ item.classes }}"{% if item.index is defined and item.index %} data-qa="list-item-{{ loop.index }}"{% endif %}{% if item.target is defined and item.target %} target="{{ item.target }}"{% endif %}{% if item.rel is defined and item.rel %} rel="{{ item.rel }}"{% endif %}>
                            {%- if item.prefix is defined and item.prefix -%}<span class="ons-u-vh">{{- item.prefix -}}</span>{%- endif -%} {{- itemText | safe -}}
                            {%- if item.target is defined and item.target == "_blank" -%}<span class="ons-u-vh">{{- item.screenreaderMessage | default("this link will open in a new tab") -}}</span>{%- endif -%}
                        </a>
                    {%- endif -%}
                {%- else -%}
                    {{- itemText | safe -}}
                {%- endif -%}
                {%- if item.suffix is defined and item.suffix or (params.iconPosition is defined and params.iconPosition == 'after') -%}
                    <span class="ons-list__suffix"{% if listEl != 'ol' %} aria-hidden="true"{% endif %}>
                    {%- if item.suffix is defined and item.suffix -%}
                        {{- item.suffix -}}
                    {%- elif (item.index is defined and item.index and listEl != 'ol') or (item.index is defined and item.index and listEl == 'ol' and 'bare' in variants) -%}
                        {{- loop.index -}}
                    {% elif params.iconPosition is defined and params.iconPosition == 'after' %}
                        {% from "components/icons/_macro.njk" import onsIcon %}
                        {{
                            onsIcon({
                                "iconType": iconType,
                                "iconSize": params.iconSize
                            })
                        }}
                    {%- endif -%} </span>
                {%- endif -%}
            {% if listLength > 1 %}</li>{%- endif -%}
        {%- endfor -%}
    </{{listEl}}>
{% endmacro %}
.ons-list {
  margin: 0 0 1rem;
  padding: 0 0 0 1.5rem;

  &__item {
    &:last-child {
      margin-bottom: 0;
    }
  }

  &--spacious {
    .ons-list__item {
      margin: 0 0 1.5rem;
    }
  }

  &--bare {
    list-style: none;
    padding-left: 0;
  }

  &--dashed {
    @extend .ons-list--bare;
    .ons-list__item {
      margin-left: 25px;
      position: relative;
      &::before {
        border-top: 1px solid $color-black;
        content: '';
        left: 0;
        margin-left: -25px;
        position: absolute;
        top: 14px;
        width: 15px;
      }
    }
  }

  &__link {
    display: inline-block;
    margin-right: 1rem;
    vertical-align: top;
    white-space: normal;
  }

  &__prefix {
    margin-right: 0.5rem;
  }

  &__suffix {
    margin-left: 0.5rem;
  }

  &__prefix,
  &__suffix {
    font-family: $font-mono;
  }

  &--prefix &,
  &--suffix &,
  &--icons & {
    &__item {
      align-items: flex-start;
      display: flex;
    }
  }

  &--social & {
    &__item {
      align-items: center;
    }
  }

  &--icons {
    margin-bottom: 0;
    .ons-list__item {
      margin-bottom: 0.5rem;
    }
  }

  &--languages {
    margin-bottom: 0;
    .ons-list__link {
      margin-right: 0;
    }
  }
}

@include bp-suffix('ons-list--inline') {
  &:not(.ons-list--icons) {
    margin: 0 1rem 0 0;
    .ons-list__item {
      display: inline-block;
      margin: 0 1rem 0 0;
      vertical-align: top;
    }
  }

  &.ons-list--icons {
    align-items: center;
    display: flex;
    flex-wrap: wrap;
  }
}

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.

<ul class="ons-list ons-list--bare ons-list--icons">
  <li class="ons-list__item">
    <span class="ons-list__prefix" aria-hidden="true">
      <svg class="ons-svg-icon " viewBox="0 0 13 10" xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor">
        <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-svg-icon " viewBox="0 0 13 10" xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor">
        <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-svg-icon " viewBox="0 0 13 10" xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor">
        <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>
{% from "components/lists/_macro.njk" import onsList %}
{{
    onsList({
        "iconPosition": "before",
        "iconType": "check",
        "itemsList": [
            {
                "text": "birth certificate"
            },
            {
                "text": "national insurance number"
            },
            {
                "text": "passport"
            }
        ]
    })
}}
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 id for the wrapping element
classes string false Classes to be added to the wrapping element
itemsList Array<ListItem> true An array of items to show in the list
variants array or string false An array of values or single value (string) to adjust the ‘list’ display using available variants - bare, dashed, inline, social, languages
iconPosition string true Sets position of icon to before or after all the list items
iconSize string true Icon size can be set to m, l, xl, xxl
iconType string true Adds an icon to all the list items when set to the name of one of the available icons

ListItem

Name Type Required Description
text string true The text for the list item
title string false The text for the list item - only used for craft
url string false Will wrap the text in a link
listClasses string false Classes to be added to the list item
variants string false Used for variations. Available variants values: inPageLink for use with error lists when a url is also provided
rel string false allows setting of rel attribute for list item links
target string false If url is provided this will set the target for that link
screenreaderMessage string false Sets a message to be read out by screen readers when target is set to _blank and link opens in a new tab. Defaults to this link will open in a new tab if not set
index boolean false Will prefix the list item with index number if set to true
external boolean false Will style the item like an external link
prefix string true Will prefix the list item with whatever prefix is set to
suffix string true Will suffix the list item with whatever suffix is set to
iconType string true Adds an icon to the list item when set to the name of one of the available icons
{% macro onsList(params) %}
    {% set variants = params.variants if params.variants else '' %}
    {% set listLength = params.itemsList | length %}

    {% if params.itemsList[0] is defined and params.itemsList[0].prefix %}
        {% set otherClasses = 'ons-list--bare ons-list--prefix' %}
    {% elif params.itemsList[0] is defined and params.itemsList[0].suffix %}
        {% set otherClasses = 'ons-list--bare ons-list--suffix' %}
    {% elif params.itemsList[0] is defined and params.iconPosition is defined and params.iconPosition %}
        {% set otherClasses = 'ons-list--bare ons-list--icons' %}
        {% set iconType = params.iconType if params.iconType else '' %}
    {% else %}
        {% set otherClasses = '' %}
    {% endif %}

    {% if listLength < 2 %}
        {% set listEl = 'p' %}
    {% elif params.element is defined and params.element %}
        {% set listEl = params.element | lower %}
    {% else %}
        {% set listEl = 'ul' %}
    {% endif %}

    <{{listEl}} {% if params.id is defined and params.id %}id="{{ params.id }} "{% endif %}class="{% if listLength > 1 %}ons-list{% endif %}{% if params.classes is defined and params.classes %} {{ params.classes -}}{% endif %}{% if params.variants is defined and params.variants %}{% if params.variants is not string %}{% for variant in params.variants %} ons-list--{{ variant }}{% endfor %}{% else %} ons-list--{{ params.variants }}{% endif %}{% endif %}{% if otherClasses %} {{ otherClasses -}}{% endif %}">
        {%- for item in (params.itemsList if params.itemsList is iterable else params.itemsList.items()) -%}
            {% if listLength > 1 %}<li class="ons-list__item{% if item.listClasses is defined and item.listClasses %} {{ item.listClasses }}{% endif %}"{% if item.current is defined and item.current %} aria-current="true"{% endif %}>{% endif %}

                {% set itemText = item.text %}

                {% if params.itemsList[0] is defined and item.iconType is defined and item.iconType %}
                    {% set iconType = item.iconType if item.iconType else '' %}
                {% endif %}

                {# For Craft support we also support title and navigation title #}
                {% if item.navigationTitle is defined and item.navigationTitle %}
                    {% set itemText = item.navigationTitle %}
                {% elif item.title is defined and item.title %}
                    {% set itemText = item.title %}
                {% endif %}

                {%- if item.index is defined and item.index or item.prefix is defined and item.prefix or (params.iconPosition is defined and params.iconPosition == 'before') -%}
                    <span class="ons-list__prefix"{% if listEl != 'ol' %} aria-hidden="true"{% endif %}>
                    {%- if item.prefix is defined and item.prefix -%}
                        {{- item.prefix -}}.
                    {%- elif (item.index is defined and item.index and listEl != 'ol') or (item.index is defined and item.index and listEl == 'ol' and 'bare' in variants) -%}
                        {{- loop.index -}}.
                    {% elif params.iconPosition is defined and params.iconPosition == 'before' %}
                        {% from "components/icons/_macro.njk" import onsIcon %}
                        {{
                            onsIcon({
                                "iconType": iconType,
                                "iconSize": params.iconSize
                            })
                        }}
                    {%- endif -%}
                    </span>
                {%- endif -%}
                {%- if item.url is defined and item.url and item.current != true -%}
                    {%- if item.external is defined and item.external -%}
                        {% from "components/external-link/_macro.njk" import onsExternalLink %}
                        {{
                            onsExternalLink({
                                "url": item.url,
                                "linkText": itemText
                            })
                        }}
                    {%- else -%}
                        <a href="{{ item.url }}" class="ons-list__link {% if item.variant == 'inPageLink' %}ons-js-inpagelink {% endif %} {{ item.classes }}"{% if item.index is defined and item.index %} data-qa="list-item-{{ loop.index }}"{% endif %}{% if item.target is defined and item.target %} target="{{ item.target }}"{% endif %}{% if item.rel is defined and item.rel %} rel="{{ item.rel }}"{% endif %}>
                            {%- if item.prefix is defined and item.prefix -%}<span class="ons-u-vh">{{- item.prefix -}}</span>{%- endif -%} {{- itemText | safe -}}
                            {%- if item.target is defined and item.target == "_blank" -%}<span class="ons-u-vh">{{- item.screenreaderMessage | default("this link will open in a new tab") -}}</span>{%- endif -%}
                        </a>
                    {%- endif -%}
                {%- else -%}
                    {{- itemText | safe -}}
                {%- endif -%}
                {%- if item.suffix is defined and item.suffix or (params.iconPosition is defined and params.iconPosition == 'after') -%}
                    <span class="ons-list__suffix"{% if listEl != 'ol' %} aria-hidden="true"{% endif %}>
                    {%- if item.suffix is defined and item.suffix -%}
                        {{- item.suffix -}}
                    {%- elif (item.index is defined and item.index and listEl != 'ol') or (item.index is defined and item.index and listEl == 'ol' and 'bare' in variants) -%}
                        {{- loop.index -}}
                    {% elif params.iconPosition is defined and params.iconPosition == 'after' %}
                        {% from "components/icons/_macro.njk" import onsIcon %}
                        {{
                            onsIcon({
                                "iconType": iconType,
                                "iconSize": params.iconSize
                            })
                        }}
                    {%- endif -%} </span>
                {%- endif -%}
            {% if listLength > 1 %}</li>{%- endif -%}
        {%- endfor -%}
    </{{listEl}}>
{% endmacro %}
.ons-list {
  margin: 0 0 1rem;
  padding: 0 0 0 1.5rem;

  &__item {
    &:last-child {
      margin-bottom: 0;
    }
  }

  &--spacious {
    .ons-list__item {
      margin: 0 0 1.5rem;
    }
  }

  &--bare {
    list-style: none;
    padding-left: 0;
  }

  &--dashed {
    @extend .ons-list--bare;
    .ons-list__item {
      margin-left: 25px;
      position: relative;
      &::before {
        border-top: 1px solid $color-black;
        content: '';
        left: 0;
        margin-left: -25px;
        position: absolute;
        top: 14px;
        width: 15px;
      }
    }
  }

  &__link {
    display: inline-block;
    margin-right: 1rem;
    vertical-align: top;
    white-space: normal;
  }

  &__prefix {
    margin-right: 0.5rem;
  }

  &__suffix {
    margin-left: 0.5rem;
  }

  &__prefix,
  &__suffix {
    font-family: $font-mono;
  }

  &--prefix &,
  &--suffix &,
  &--icons & {
    &__item {
      align-items: flex-start;
      display: flex;
    }
  }

  &--social & {
    &__item {
      align-items: center;
    }
  }

  &--icons {
    margin-bottom: 0;
    .ons-list__item {
      margin-bottom: 0.5rem;
    }
  }

  &--languages {
    margin-bottom: 0;
    .ons-list__link {
      margin-right: 0;
    }
  }
}

@include bp-suffix('ons-list--inline') {
  &:not(.ons-list--icons) {
    margin: 0 1rem 0 0;
    .ons-list__item {
      display: inline-block;
      margin: 0 1rem 0 0;
      vertical-align: top;
    }
  }

  &.ons-list--icons {
    align-items: center;
    display: flex;
    flex-wrap: wrap;
  }
}

List with icon suffix

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

<ul class="ons-list ons-list--bare ons-list--icons">
  <li class="ons-list__item">
    birth certificate<span class="ons-list__suffix" aria-hidden="true">
      <svg class="ons-svg-icon " viewBox="0 0 13 10" xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor">
        <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-svg-icon " viewBox="0 0 13 10" xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor">
        <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-svg-icon " viewBox="0 0 13 10" xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor">
        <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>
{% from "components/lists/_macro.njk" import onsList %}
{{
    onsList({
        "iconPosition": "after",
        "iconType": "check",
        "itemsList": [
            {
                "text": "birth certificate"
            },
            {
                "text": "national insurance number"
            },
            {
                "text": "passport"
            }
        ]
    })
}}
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 id for the wrapping element
classes string false Classes to be added to the wrapping element
itemsList Array<ListItem> true An array of items to show in the list
variants array or string false An array of values or single value (string) to adjust the ‘list’ display using available variants - bare, dashed, inline, social, languages
iconPosition string true Sets position of icon to before or after all the list items
iconSize string true Icon size can be set to m, l, xl, xxl
iconType string true Adds an icon to all the list items when set to the name of one of the available icons

ListItem

Name Type Required Description
text string true The text for the list item
title string false The text for the list item - only used for craft
url string false Will wrap the text in a link
listClasses string false Classes to be added to the list item
variants string false Used for variations. Available variants values: inPageLink for use with error lists when a url is also provided
rel string false allows setting of rel attribute for list item links
target string false If url is provided this will set the target for that link
screenreaderMessage string false Sets a message to be read out by screen readers when target is set to _blank and link opens in a new tab. Defaults to this link will open in a new tab if not set
index boolean false Will prefix the list item with index number if set to true
external boolean false Will style the item like an external link
prefix string true Will prefix the list item with whatever prefix is set to
suffix string true Will suffix the list item with whatever suffix is set to
iconType string true Adds an icon to the list item when set to the name of one of the available icons
{% macro onsList(params) %}
    {% set variants = params.variants if params.variants else '' %}
    {% set listLength = params.itemsList | length %}

    {% if params.itemsList[0] is defined and params.itemsList[0].prefix %}
        {% set otherClasses = 'ons-list--bare ons-list--prefix' %}
    {% elif params.itemsList[0] is defined and params.itemsList[0].suffix %}
        {% set otherClasses = 'ons-list--bare ons-list--suffix' %}
    {% elif params.itemsList[0] is defined and params.iconPosition is defined and params.iconPosition %}
        {% set otherClasses = 'ons-list--bare ons-list--icons' %}
        {% set iconType = params.iconType if params.iconType else '' %}
    {% else %}
        {% set otherClasses = '' %}
    {% endif %}

    {% if listLength < 2 %}
        {% set listEl = 'p' %}
    {% elif params.element is defined and params.element %}
        {% set listEl = params.element | lower %}
    {% else %}
        {% set listEl = 'ul' %}
    {% endif %}

    <{{listEl}} {% if params.id is defined and params.id %}id="{{ params.id }} "{% endif %}class="{% if listLength > 1 %}ons-list{% endif %}{% if params.classes is defined and params.classes %} {{ params.classes -}}{% endif %}{% if params.variants is defined and params.variants %}{% if params.variants is not string %}{% for variant in params.variants %} ons-list--{{ variant }}{% endfor %}{% else %} ons-list--{{ params.variants }}{% endif %}{% endif %}{% if otherClasses %} {{ otherClasses -}}{% endif %}">
        {%- for item in (params.itemsList if params.itemsList is iterable else params.itemsList.items()) -%}
            {% if listLength > 1 %}<li class="ons-list__item{% if item.listClasses is defined and item.listClasses %} {{ item.listClasses }}{% endif %}"{% if item.current is defined and item.current %} aria-current="true"{% endif %}>{% endif %}

                {% set itemText = item.text %}

                {% if params.itemsList[0] is defined and item.iconType is defined and item.iconType %}
                    {% set iconType = item.iconType if item.iconType else '' %}
                {% endif %}

                {# For Craft support we also support title and navigation title #}
                {% if item.navigationTitle is defined and item.navigationTitle %}
                    {% set itemText = item.navigationTitle %}
                {% elif item.title is defined and item.title %}
                    {% set itemText = item.title %}
                {% endif %}

                {%- if item.index is defined and item.index or item.prefix is defined and item.prefix or (params.iconPosition is defined and params.iconPosition == 'before') -%}
                    <span class="ons-list__prefix"{% if listEl != 'ol' %} aria-hidden="true"{% endif %}>
                    {%- if item.prefix is defined and item.prefix -%}
                        {{- item.prefix -}}.
                    {%- elif (item.index is defined and item.index and listEl != 'ol') or (item.index is defined and item.index and listEl == 'ol' and 'bare' in variants) -%}
                        {{- loop.index -}}.
                    {% elif params.iconPosition is defined and params.iconPosition == 'before' %}
                        {% from "components/icons/_macro.njk" import onsIcon %}
                        {{
                            onsIcon({
                                "iconType": iconType,
                                "iconSize": params.iconSize
                            })
                        }}
                    {%- endif -%}
                    </span>
                {%- endif -%}
                {%- if item.url is defined and item.url and item.current != true -%}
                    {%- if item.external is defined and item.external -%}
                        {% from "components/external-link/_macro.njk" import onsExternalLink %}
                        {{
                            onsExternalLink({
                                "url": item.url,
                                "linkText": itemText
                            })
                        }}
                    {%- else -%}
                        <a href="{{ item.url }}" class="ons-list__link {% if item.variant == 'inPageLink' %}ons-js-inpagelink {% endif %} {{ item.classes }}"{% if item.index is defined and item.index %} data-qa="list-item-{{ loop.index }}"{% endif %}{% if item.target is defined and item.target %} target="{{ item.target }}"{% endif %}{% if item.rel is defined and item.rel %} rel="{{ item.rel }}"{% endif %}>
                            {%- if item.prefix is defined and item.prefix -%}<span class="ons-u-vh">{{- item.prefix -}}</span>{%- endif -%} {{- itemText | safe -}}
                            {%- if item.target is defined and item.target == "_blank" -%}<span class="ons-u-vh">{{- item.screenreaderMessage | default("this link will open in a new tab") -}}</span>{%- endif -%}
                        </a>
                    {%- endif -%}
                {%- else -%}
                    {{- itemText | safe -}}
                {%- endif -%}
                {%- if item.suffix is defined and item.suffix or (params.iconPosition is defined and params.iconPosition == 'after') -%}
                    <span class="ons-list__suffix"{% if listEl != 'ol' %} aria-hidden="true"{% endif %}>
                    {%- if item.suffix is defined and item.suffix -%}
                        {{- item.suffix -}}
                    {%- elif (item.index is defined and item.index and listEl != 'ol') or (item.index is defined and item.index and listEl == 'ol' and 'bare' in variants) -%}
                        {{- loop.index -}}
                    {% elif params.iconPosition is defined and params.iconPosition == 'after' %}
                        {% from "components/icons/_macro.njk" import onsIcon %}
                        {{
                            onsIcon({
                                "iconType": iconType,
                                "iconSize": params.iconSize
                            })
                        }}
                    {%- endif -%} </span>
                {%- endif -%}
            {% if listLength > 1 %}</li>{%- endif -%}
        {%- endfor -%}
    </{{listEl}}>
{% endmacro %}
.ons-list {
  margin: 0 0 1rem;
  padding: 0 0 0 1.5rem;

  &__item {
    &:last-child {
      margin-bottom: 0;
    }
  }

  &--spacious {
    .ons-list__item {
      margin: 0 0 1.5rem;
    }
  }

  &--bare {
    list-style: none;
    padding-left: 0;
  }

  &--dashed {
    @extend .ons-list--bare;
    .ons-list__item {
      margin-left: 25px;
      position: relative;
      &::before {
        border-top: 1px solid $color-black;
        content: '';
        left: 0;
        margin-left: -25px;
        position: absolute;
        top: 14px;
        width: 15px;
      }
    }
  }

  &__link {
    display: inline-block;
    margin-right: 1rem;
    vertical-align: top;
    white-space: normal;
  }

  &__prefix {
    margin-right: 0.5rem;
  }

  &__suffix {
    margin-left: 0.5rem;
  }

  &__prefix,
  &__suffix {
    font-family: $font-mono;
  }

  &--prefix &,
  &--suffix &,
  &--icons & {
    &__item {
      align-items: flex-start;
      display: flex;
    }
  }

  &--social & {
    &__item {
      align-items: center;
    }
  }

  &--icons {
    margin-bottom: 0;
    .ons-list__item {
      margin-bottom: 0.5rem;
    }
  }

  &--languages {
    margin-bottom: 0;
    .ons-list__link {
      margin-right: 0;
    }
  }
}

@include bp-suffix('ons-list--inline') {
  &:not(.ons-list--icons) {
    margin: 0 1rem 0 0;
    .ons-list__item {
      display: inline-block;
      margin: 0 1rem 0 0;
      vertical-align: top;
    }
  }

  &.ons-list--icons {
    align-items: center;
    display: flex;
    flex-wrap: wrap;
  }
}

Inline list with icon prefix

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.

<ul class="ons-list ons-list--social ons-list--inline ons-list--bare ons-list--icons">
  <li class="ons-list__item">
    <span class="ons-list__prefix" aria-hidden="true">
      <svg class="ons-svg-icon ons-svg-icon--xxl " id="icon-twitter" viewBox="0 0 32 32" xmlns="http://www.w3.org/2000/svg" focusable="false" aria-hidden="true">
        <path d="M24.04,12.95c0,0.17,0,0.33,0,0.5c0.01,4.01-2.17,7.71-5.69,9.64c-3.52,1.93-7.81,1.78-11.19-0.38c0.31,0.04,0.61,0.05,0.92,0.05c1.73,0,3.42-0.58,4.78-1.65c-1.65-0.04-3.09-1.11-3.6-2.68c0.25,0.05,0.51,0.07,0.76,0.07c0.34,0,0.68-0.05,1.01-0.14C9.23,18,7.93,16.4,7.95,14.55v-0.05c0.54,0.29,1.13,0.46,1.74,0.48c-1.66-1.12-2.2-3.33-1.23-5.08c1.96,2.41,4.85,3.87,7.95,4.03c-0.07-0.29-0.1-0.58-0.1-0.88c0-1.58,0.97-3,2.44-3.59c1.47-0.58,3.15-0.21,4.23,0.94c0.86-0.17,1.69-0.49,2.45-0.94c-0.28,0.9-0.88,1.65-1.69,2.13c0.76-0.09,1.51-0.29,2.21-0.6C25.43,11.76,24.79,12.42,24.04,12.95zM16,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  " rel="noreferrer external">Twitter</a>
  </li>
  <li class="ons-list__item">
    <span class="ons-list__prefix" aria-hidden="true">
      <svg class="ons-svg-icon ons-svg-icon--xxl " id="icon-facebook" viewBox="0 0 32 32" xmlns="http://www.w3.org/2000/svg" focusable="false" aria-hidden="true">
        <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  " rel="noreferrer external">Facebook</a>
  </li>
  <li class="ons-list__item">
    <span class="ons-list__prefix" aria-hidden="true">
      <svg class="ons-svg-icon ons-svg-icon--xxl " id="icon-instagram" viewBox="0 0 32 32" xmlns="http://www.w3.org/2000/svg" focusable="false" aria-hidden="true">
        <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  " rel="noreferrer external">Instagram</a>
  </li>
  <li class="ons-list__item">
    <span class="ons-list__prefix" aria-hidden="true">
      <svg class="ons-svg-icon ons-svg-icon--xxl " id="icon-linkedin" viewBox="0 0 32 32" xmlns="http://www.w3.org/2000/svg" focusable="false" aria-hidden="true">
        <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  " rel="noreferrer external">LinkedIn</a>
  </li>
</ul>
{% from "components/lists/_macro.njk" import onsList %}
{{
    onsList({
        "variants": ['social', 'inline'],
        "iconPosition": 'before',
        "iconSize": 'xxl',
        "itemsList": [
            {
                "url": '#0',
                "text": 'Twitter',
                "iconType": 'twitter',
                "rel": 'noreferrer external'
            },
            {
                "url": '#0',
                "text": 'Facebook',
                "iconType": 'facebook',
                "rel": 'noreferrer external'
            },
            {
                "url": '#0',
                "text": 'Instagram',
                "iconType": 'instagram',
                "rel": 'noreferrer external'
            },
            {
                "url": '#0',
                "text": 'LinkedIn',
                "iconType": 'linkedin',
                "rel": 'noreferrer external'
            }
        ]
    })
}}
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 id for the wrapping element
classes string false Classes to be added to the wrapping element
itemsList Array<ListItem> true An array of items to show in the list
variants array or string false An array of values or single value (string) to adjust the ‘list’ display using available variants - bare, dashed, inline, social, languages
iconPosition string true Sets position of icon to before or after all the list items
iconSize string true Icon size can be set to m, l, xl, xxl
iconType string true Adds an icon to all the list items when set to the name of one of the available icons

ListItem

Name Type Required Description
text string true The text for the list item
title string false The text for the list item - only used for craft
url string false Will wrap the text in a link
listClasses string false Classes to be added to the list item
variants string false Used for variations. Available variants values: inPageLink for use with error lists when a url is also provided
rel string false allows setting of rel attribute for list item links
target string false If url is provided this will set the target for that link
screenreaderMessage string false Sets a message to be read out by screen readers when target is set to _blank and link opens in a new tab. Defaults to this link will open in a new tab if not set
index boolean false Will prefix the list item with index number if set to true
external boolean false Will style the item like an external link
prefix string true Will prefix the list item with whatever prefix is set to
suffix string true Will suffix the list item with whatever suffix is set to
iconType string true Adds an icon to the list item when set to the name of one of the available icons
{% macro onsList(params) %}
    {% set variants = params.variants if params.variants else '' %}
    {% set listLength = params.itemsList | length %}

    {% if params.itemsList[0] is defined and params.itemsList[0].prefix %}
        {% set otherClasses = 'ons-list--bare ons-list--prefix' %}
    {% elif params.itemsList[0] is defined and params.itemsList[0].suffix %}
        {% set otherClasses = 'ons-list--bare ons-list--suffix' %}
    {% elif params.itemsList[0] is defined and params.iconPosition is defined and params.iconPosition %}
        {% set otherClasses = 'ons-list--bare ons-list--icons' %}
        {% set iconType = params.iconType if params.iconType else '' %}
    {% else %}
        {% set otherClasses = '' %}
    {% endif %}

    {% if listLength < 2 %}
        {% set listEl = 'p' %}
    {% elif params.element is defined and params.element %}
        {% set listEl = params.element | lower %}
    {% else %}
        {% set listEl = 'ul' %}
    {% endif %}

    <{{listEl}} {% if params.id is defined and params.id %}id="{{ params.id }} "{% endif %}class="{% if listLength > 1 %}ons-list{% endif %}{% if params.classes is defined and params.classes %} {{ params.classes -}}{% endif %}{% if params.variants is defined and params.variants %}{% if params.variants is not string %}{% for variant in params.variants %} ons-list--{{ variant }}{% endfor %}{% else %} ons-list--{{ params.variants }}{% endif %}{% endif %}{% if otherClasses %} {{ otherClasses -}}{% endif %}">
        {%- for item in (params.itemsList if params.itemsList is iterable else params.itemsList.items()) -%}
            {% if listLength > 1 %}<li class="ons-list__item{% if item.listClasses is defined and item.listClasses %} {{ item.listClasses }}{% endif %}"{% if item.current is defined and item.current %} aria-current="true"{% endif %}>{% endif %}

                {% set itemText = item.text %}

                {% if params.itemsList[0] is defined and item.iconType is defined and item.iconType %}
                    {% set iconType = item.iconType if item.iconType else '' %}
                {% endif %}

                {# For Craft support we also support title and navigation title #}
                {% if item.navigationTitle is defined and item.navigationTitle %}
                    {% set itemText = item.navigationTitle %}
                {% elif item.title is defined and item.title %}
                    {% set itemText = item.title %}
                {% endif %}

                {%- if item.index is defined and item.index or item.prefix is defined and item.prefix or (params.iconPosition is defined and params.iconPosition == 'before') -%}
                    <span class="ons-list__prefix"{% if listEl != 'ol' %} aria-hidden="true"{% endif %}>
                    {%- if item.prefix is defined and item.prefix -%}
                        {{- item.prefix -}}.
                    {%- elif (item.index is defined and item.index and listEl != 'ol') or (item.index is defined and item.index and listEl == 'ol' and 'bare' in variants) -%}
                        {{- loop.index -}}.
                    {% elif params.iconPosition is defined and params.iconPosition == 'before' %}
                        {% from "components/icons/_macro.njk" import onsIcon %}
                        {{
                            onsIcon({
                                "iconType": iconType,
                                "iconSize": params.iconSize
                            })
                        }}
                    {%- endif -%}
                    </span>
                {%- endif -%}
                {%- if item.url is defined and item.url and item.current != true -%}
                    {%- if item.external is defined and item.external -%}
                        {% from "components/external-link/_macro.njk" import onsExternalLink %}
                        {{
                            onsExternalLink({
                                "url": item.url,
                                "linkText": itemText
                            })
                        }}
                    {%- else -%}
                        <a href="{{ item.url }}" class="ons-list__link {% if item.variant == 'inPageLink' %}ons-js-inpagelink {% endif %} {{ item.classes }}"{% if item.index is defined and item.index %} data-qa="list-item-{{ loop.index }}"{% endif %}{% if item.target is defined and item.target %} target="{{ item.target }}"{% endif %}{% if item.rel is defined and item.rel %} rel="{{ item.rel }}"{% endif %}>
                            {%- if item.prefix is defined and item.prefix -%}<span class="ons-u-vh">{{- item.prefix -}}</span>{%- endif -%} {{- itemText | safe -}}
                            {%- if item.target is defined and item.target == "_blank" -%}<span class="ons-u-vh">{{- item.screenreaderMessage | default("this link will open in a new tab") -}}</span>{%- endif -%}
                        </a>
                    {%- endif -%}
                {%- else -%}
                    {{- itemText | safe -}}
                {%- endif -%}
                {%- if item.suffix is defined and item.suffix or (params.iconPosition is defined and params.iconPosition == 'after') -%}
                    <span class="ons-list__suffix"{% if listEl != 'ol' %} aria-hidden="true"{% endif %}>
                    {%- if item.suffix is defined and item.suffix -%}
                        {{- item.suffix -}}
                    {%- elif (item.index is defined and item.index and listEl != 'ol') or (item.index is defined and item.index and listEl == 'ol' and 'bare' in variants) -%}
                        {{- loop.index -}}
                    {% elif params.iconPosition is defined and params.iconPosition == 'after' %}
                        {% from "components/icons/_macro.njk" import onsIcon %}
                        {{
                            onsIcon({
                                "iconType": iconType,
                                "iconSize": params.iconSize
                            })
                        }}
                    {%- endif -%} </span>
                {%- endif -%}
            {% if listLength > 1 %}</li>{%- endif -%}
        {%- endfor -%}
    </{{listEl}}>
{% endmacro %}
.ons-list {
  margin: 0 0 1rem;
  padding: 0 0 0 1.5rem;

  &__item {
    &:last-child {
      margin-bottom: 0;
    }
  }

  &--spacious {
    .ons-list__item {
      margin: 0 0 1.5rem;
    }
  }

  &--bare {
    list-style: none;
    padding-left: 0;
  }

  &--dashed {
    @extend .ons-list--bare;
    .ons-list__item {
      margin-left: 25px;
      position: relative;
      &::before {
        border-top: 1px solid $color-black;
        content: '';
        left: 0;
        margin-left: -25px;
        position: absolute;
        top: 14px;
        width: 15px;
      }
    }
  }

  &__link {
    display: inline-block;
    margin-right: 1rem;
    vertical-align: top;
    white-space: normal;
  }

  &__prefix {
    margin-right: 0.5rem;
  }

  &__suffix {
    margin-left: 0.5rem;
  }

  &__prefix,
  &__suffix {
    font-family: $font-mono;
  }

  &--prefix &,
  &--suffix &,
  &--icons & {
    &__item {
      align-items: flex-start;
      display: flex;
    }
  }

  &--social & {
    &__item {
      align-items: center;
    }
  }

  &--icons {
    margin-bottom: 0;
    .ons-list__item {
      margin-bottom: 0.5rem;
    }
  }

  &--languages {
    margin-bottom: 0;
    .ons-list__link {
      margin-right: 0;
    }
  }
}

@include bp-suffix('ons-list--inline') {
  &:not(.ons-list--icons) {
    margin: 0 1rem 0 0;
    .ons-list__item {
      display: inline-block;
      margin: 0 1rem 0 0;
      vertical-align: top;
    }
  }

  &.ons-list--icons {
    align-items: center;
    display: flex;
    flex-wrap: wrap;
  }
}

Quotes

Use when displaying a short quote.

<blockquote class="ons-quote">
  <svg class="ons-svg-icon " viewBox="0 0 14 10" xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor">
    <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>
{% from "components/quote/_macro.njk" import onsQuote %}
{{-
    onsQuote({
        "text": 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
        "ref": 'A N Other',
        "textFontSize": "l"
    })
}}
{% macro onsQuote(params) %}
    <blockquote class="ons-quote">
        {% from "components/icons/_macro.njk" import onsIcon %}
        {{
            onsIcon({
                "iconType": 'quote'
            })
        }}
        <span class="ons-quote__text ons-u-fs-{{ params.textFontSize if params.textFontSize is defined and params.textFontSize else 'l' }}">{{ caller() if caller else params.text | safe }}</span>
        {% if params.ref is defined and params.ref %}<span class="ons-quote__ref">&mdash; {{ params.ref | safe }}</span>{% endif %}
    </blockquote>
{% endmacro %}
.ons-quote {
  background-size: 2rem;
  margin: 0 0 1rem;
  padding: 0 0 0 3em;
  position: relative;

  &__text {
    display: block;
  }

  &__ref {
    @extend .ons-u-fs-s;

    color: $color-text-light;
    display: block;
    margin-top: 0.5rem;
    position: relative;
  }

  .ons-svg-icon {
    fill: $color-grey-75 !important;
    height: 1.85rem;
    left: 0;
    position: absolute;
    top: -0.125rem;
    width: 1.85rem;

    @include mq(m) {
      top: 0;
    }
  }
}

Addresses

Use when displaying an address.

<div class="ons-address-output">
  <p class="ons-address-output__lines">
    Unit 5<br>
    Trescos<br>
    Abingdon Road<br>
    Goathill<br>
    Barry<br>
    AB12 6UH
  </p>
</div>
{% from "components/address-output/_macro.njk" import onsAddressOutput %}
{{-
    onsAddressOutput({
        unit: 'Unit 5',
        organisation: 'Trescos',
        line1: 'Abingdon Road',
        line2: 'Goathill',
        town: 'Barry',
        postcode: 'AB12 6UH'
    })
}}
Name Type Required Description
classes string false Classes to add to the container
unit AddressField false Text for the unit field
organisation AddressField false Text for the organisation field
line1 AddressField false Text for the line1 field
line2 AddressField false Text for the line2 field
town AddressField false Text for the town field
postcode AddressField false Text for the postcode field
{% macro onsAddressOutput(params) %}
    <div class="ons-address-output{% if params.classes is defined and params.classes %} {{ params.classes }}{% endif %}">
        <p class="ons-address-output__lines">
            {% if params.unit is defined and params.unit %}
                {{ params.unit }}<br>
            {% endif %}
            {% if params.organisation is defined and params.organisation %}
                {{ params.organisation }}<br>
            {% endif %}
            {% if params.line1 is defined and params.line1 %}
                {{ params.line1 }}<br>
            {% endif %}
            {% if params.line2 is defined and params.line2 %}
                {{ params.line2 }}<br>
            {% endif %}
            {% if params.town is defined and params.town %}
                {{ params.town }}<br>
            {% endif %}
            {% if params.postcode is defined and params.postcode %}
                {{ params.postcode }}
            {% endif %}
        </p>
    </div>
{% endmacro %}
.ons-address-output {
  &__lines {
    margin-bottom: 0;
  }
}

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.

<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>
{% 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>'
    })
}}
{% macro onsTextIndent(params) %}
    <div class="ons-text-indent">
        {{ caller() if caller else params.text | safe }}
    </div>
{% endmacro %}
.ons-text-indent {
  border-left: 4px solid $color-borders-indent;
  margin: 0 0 1rem;
  padding: 0 0 0 1.3em;
}

Help improve this foundation

Let us know how we could improve this foundation or share your user research findings. Discuss the ‘Typography’ foundation on Github