Style Icons
Overview
An icon can help explain the function of an element, such as a call to action.
When to use icons
Icons can make scanning a page quicker, as well as making target areas larger and easier to select. They can also help users with accessibility needs.
You can use an icon with a:
How to use icons
Use recognisable icons
Always consider if an icon is necessary, and only use icons that are universally understood. An icon that means different things to different people will make your product harder to use.
Our icons are supported by user research and are available from our icon set.
A selection of icons are labelled as suitable for use with web user interfaces, with the Nunjucks code available on the individual icon pages. This guidance details how to use these icons as part of a Design System component.
There is further guidance available on how we design our icons.
Use a label
Always use an icon with a text label. Using icons on their own means the user must think more, especially if the icon is not familiar to them.
Place icons before text to show function
Place an icon before the text to help the user understand the function of the element.
For example, a user can quickly see the printer icon first on the print button.
Example Button Print contents
Nunjucks
{% from "components/button/_macro.njk" import onsButton %}
{{
onsButton({
"text": 'Print this page',
"variants": ['print', 'small', 'secondary']
})
}}
Nunjucks macro options
| Name | Type | Required | Description |
|---|---|---|---|
| text | string | true (unless html is set) | Text label for the button |
| html | string | true (unless text is set) | HTML for the button label |
| variants | array or string | false | An array of values or single value (string) to adjust the component using available variants: “small”, “secondary”, “ghost”, “disabled”, “loader”, “timer”, “print”, and “download”. |
| type | string | false | Sets the HTML type attribute for the <button>. Can be set to either: “button” or “reset”. Defaults to “submit”. |
| id | string | false | Sets the HTML id of the button |
| name | string | false | Sets the HTML name attribute for the <button>. Not valid if url is set. |
| value | string | false | Sets the HTML value attribute for the <button>. Not valid if url is set. |
| classes | string | false | Classes to add to the button component |
| innerClasses | string | false | Classes to add to the inner button element |
| url | string | false | Creates an HTML hyperlink <a> element in place of the <button> element, with the required classes and attributes. Set the URL for the href attribute. |
| newWindow | boolean | false | Set to “true” to make the button open the page set by url in a new tab. Used for links to external pages |
| newWindowDescription | string | false | Use to set context after the newWindow button’s text label for screen readers. Defaults to “opens in a new tab” |
| iconType | string | false | Adds an icon to the button, before the label, by setting the icon type |
| iconPosition | string | false | Sets the icon position of the button. |
| noIcon | boolean | false | Set to “true” to remove the button’s default icon |
| buttonContext | string | false | Use to add context after a button’s text label for screen readers. For example, the “Hide this” button in the cookies confirmation banner requires context to help let a screen reader user know what the button hides. |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the button component |
| removeDownloadAttribute | boolean | false | Removes the download attribute on the download variant when set to “true”. Use when the download button needs to be redirected, for example when a session has expired. You must also set the Content-Disposition header to make sure the file is downloaded |
| listeners | object | false | Creates a <script> element that adds an event listener to the element by id. Takes key { event } and value { function } |
HTML
<button type="button" class="ons-btn ons-btn--print ons-btn--small ons-btn--secondary ons-u-d-no ons-js-print-btn">
<span class="ons-btn__inner"><svg class="ons-icon ons-u-mr-2xs" viewBox="0 0 20 16" xmlns="http://www.w3.org/2000/svg"
focusable="false" fill="currentColor" role="img" title="ons-icon-print">
<path
d="M17 4H3C1.3 4 0 5.2 0 6.8v5.5h4V16h12v-3.7h4V6.8C20 5.2 18.7 4 17 4zm-3 10H6V9h8v5zm3-6a1 1 0 1 1 0-2 1 1 0 0 1 0 2zm-1-8H4v3h12V0z" />
</svg><span class="ons-btn__text">Print this page</span></span>
</button>Use navigation icons to show direction
A directional icon should be used with a button label or link to show the user the direction it will take them.
Use a forward navigation icon after the text and a backward navigation icon before the text.
For example, the arrow-next icon after the call to action button shows the button will move forward to the next page.
Example Button Link contents
Nunjucks
{% from "components/button/_macro.njk" import onsButton %}
{{
onsButton({
"text": 'Get started',
"url": '#0'
})
}}
Nunjucks macro options
| Name | Type | Required | Description |
|---|---|---|---|
| text | string | true (unless html is set) | Text label for the button |
| html | string | true (unless text is set) | HTML for the button label |
| variants | array or string | false | An array of values or single value (string) to adjust the component using available variants: “small”, “secondary”, “ghost”, “disabled”, “loader”, “timer”, “print”, and “download”. |
| type | string | false | Sets the HTML type attribute for the <button>. Can be set to either: “button” or “reset”. Defaults to “submit”. |
| id | string | false | Sets the HTML id of the button |
| name | string | false | Sets the HTML name attribute for the <button>. Not valid if url is set. |
| value | string | false | Sets the HTML value attribute for the <button>. Not valid if url is set. |
| classes | string | false | Classes to add to the button component |
| innerClasses | string | false | Classes to add to the inner button element |
| url | string | false | Creates an HTML hyperlink <a> element in place of the <button> element, with the required classes and attributes. Set the URL for the href attribute. |
| newWindow | boolean | false | Set to “true” to make the button open the page set by url in a new tab. Used for links to external pages |
| newWindowDescription | string | false | Use to set context after the newWindow button’s text label for screen readers. Defaults to “opens in a new tab” |
| iconType | string | false | Adds an icon to the button, before the label, by setting the icon type |
| iconPosition | string | false | Sets the icon position of the button. |
| noIcon | boolean | false | Set to “true” to remove the button’s default icon |
| buttonContext | string | false | Use to add context after a button’s text label for screen readers. For example, the “Hide this” button in the cookies confirmation banner requires context to help let a screen reader user know what the button hides. |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the button component |
| removeDownloadAttribute | boolean | false | Removes the download attribute on the download variant when set to “true”. Use when the download button needs to be redirected, for example when a session has expired. You must also set the Content-Disposition header to make sure the file is downloaded |
| listeners | object | false | Creates a <script> element that adds an event listener to the element by id. Takes key { event } and value { function } |
HTML
<a href="#0" role="button" class="ons-btn ons-btn--link ons-js-submit-btn">
<span class="ons-btn__inner"><span class="ons-btn__text">Get started</span><svg class="ons-icon ons-u-ml-2xs"
viewBox="0 0 17 13" xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor" role="img"
title="ons-icon-arrow-next">
<path
d="m10 .2-.9.9c-.1.1-.1.4 0 .5l4 4H.6c-.2 0-.4.2-.4.4v1.2c0 .2.2.4.4.4h12.5l-3.9 3.7c-.2.2-.2.4 0 .6l.8.9c.2.2.4.2.6 0L16.8 7c.2-.2.2-.4 0-.6L10.7.3c-.3-.2-.5-.2-.7-.1z" />
</svg></span>
</a>The chevron icon before the back link shows the link will move back to the previous page.
Example Breadcrumbs Single contents
Nunjucks
{% from "components/breadcrumbs/_macro.njk" import onsBreadcrumbs %}
{{
onsBreadcrumbs({
"ariaLabel": 'Breadcrumbs',
"itemsList": [
{
"url": '/',
"text": 'Home'
}
]
})
}}
Nunjucks macro options
| Name | Type | Required | Description |
|---|---|---|---|
| classes | string | false | Custom classes to add to the breadcrumbs nav element |
| ariaLabel | string | false | The aria-label added to the nav element. Defaults to “Breadcrumbs”. |
| id | string | false | The id added to the nav element |
| itemsList | Array<BreadcrumbsItem> | true | An array of breadcrumb items |
| Name | Type | Required | Description |
|---|---|---|---|
| itemClasses | string | false | Custom classes to add to the breadcrumbs list item |
| linkClasses | string | false | Custom classes to add to the breadcrumb link |
| id | string | false | The ID added to the breadcrumb link |
| url | string | true | The URL for the breadcrumb link |
| text | string | true | The title of the page the breadcrumb is linking to |
| attributes | object | false | HTML attributes (for example, data attributes) to add to the breadcrumb link |
HTML
<nav class="ons-breadcrumbs" aria-label="Breadcrumbs">
<ol class="ons-breadcrumbs__items ons-u-fs-s">
<li class="ons-breadcrumbs__item" id="breadcrumb-1">
<a class="ons-breadcrumbs__link" href="/">Home</a><svg class="ons-icon" viewBox="0 0 8 13"
xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor" role="img" title="ons-icon-chevron">
<path
d="M5.74,14.28l-.57-.56a.5.5,0,0,1,0-.71h0l5-5-5-5a.5.5,0,0,1,0-.71h0l.57-.56a.5.5,0,0,1,.71,0h0l5.93,5.93a.5.5,0,0,1,0,.7L6.45,14.28a.5.5,0,0,1-.71,0Z"
transform="translate(-5.02 -1.59)" />
</svg>
</li>
</ol>
</nav>Icon type
Use the parameter iconType to set the type of icon. The value will be the name of the “Web UI” icon, which you will need to choose from our icon set.
Icon position
You can set an icon’s position to before or after the text on a button or list.
Use the parameter iconPosition and give it a value of either “before” or ”after”.
Icon size
You can change the size of an icon on a list or panel – from the default size of regular text – to match the size of the text, as detailed in the type scale.
Use the parameter iconSize and give it a value of either: “s”, “m”, “l”, “xl”, “xxl” or “xxxl”.
Example Icons Size contents
Nunjucks
{% from "components/panel/_macro.njk" import onsPanel %}
{{
onsPanel({
"variant": 'success',
"id": 'success-id',
"iconType": 'check',
"iconSize": '3xl',
"body": '<h2 class="ons-u-fs-3xl">3xl</h2>'
})
}}
{{
onsPanel({
"variant": 'success',
"id": 'success-id',
"iconType": 'check',
"iconSize": '2xl',
"body": '<h2 class="ons-u-fs-2xl">2xl</h2>'
})
}}
{{
onsPanel({
"variant": 'success',
"id": 'success-id',
"iconType": 'check',
"iconSize": 'xl',
"body": '<h2 class="ons-u-fs-xl">xl</h2>'
})
}}
{{
onsPanel({
"variant": 'success',
"id": 'success-id',
"iconType": 'check',
"iconSize": 'l',
"body": '<h2 class="ons-u-fs-l">l</h2>'
})
}}
{{
onsPanel({
"variant": 'success',
"id": 'success-id',
"iconType": 'check',
"iconSize": 'm',
"body": '<h2 class="ons-u-fs-m">m</h2>'
})
}}
{{
onsPanel({
"variant": 'success',
"id": 'success-id',
"iconType": 'check',
"body": '<p>r</p>'
})
}}
{{
onsPanel({
"variant": 'success',
"id": 'success-id',
"iconType": 'check',
"iconSize": 's',
"body": '<p class="ons-u-fs-s">s</p>'
})
}}
HTML
<div aria-labelledby="alert" role="alert" tabindex="-1" class="ons-panel ons-panel--success ons-panel--no-title"
id="success-id">
<span id="alert" class="ons-panel__assistive-text ons-u-vh">Completed: </span>
<span class="ons-panel__icon ons-u-fs-3xl"><svg class="ons-icon ons-icon--3xl" viewBox="0 0 13 10"
xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor" role="img" title="ons-icon-check">
<path
d="M14.35,3.9l-.71-.71a.5.5,0,0,0-.71,0h0L5.79,10.34,3.07,7.61a.51.51,0,0,0-.71,0l-.71.71a.51.51,0,0,0,0,.71l3.78,3.78a.5.5,0,0,0,.71,0h0L14.35,4.6A.5.5,0,0,0,14.35,3.9Z"
transform="translate(-1.51 -3.04)" />
</svg></span>
<div class="ons-panel__body ons-icon-margin--3xl">
<h2 class="ons-u-fs-3xl">3xl</h2>
</div>
</div>
<div aria-labelledby="alert" role="alert" tabindex="-1" class="ons-panel ons-panel--success ons-panel--no-title"
id="success-id">
<span id="alert" class="ons-panel__assistive-text ons-u-vh">Completed: </span>
<span class="ons-panel__icon ons-u-fs-2xl"><svg class="ons-icon ons-icon--2xl" viewBox="0 0 13 10"
xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor" role="img" title="ons-icon-check">
<path
d="M14.35,3.9l-.71-.71a.5.5,0,0,0-.71,0h0L5.79,10.34,3.07,7.61a.51.51,0,0,0-.71,0l-.71.71a.51.51,0,0,0,0,.71l3.78,3.78a.5.5,0,0,0,.71,0h0L14.35,4.6A.5.5,0,0,0,14.35,3.9Z"
transform="translate(-1.51 -3.04)" />
</svg></span>
<div class="ons-panel__body ons-icon-margin--2xl">
<h2 class="ons-u-fs-2xl">2xl</h2>
</div>
</div>
<div aria-labelledby="alert" role="alert" tabindex="-1" class="ons-panel ons-panel--success ons-panel--no-title"
id="success-id">
<span id="alert" class="ons-panel__assistive-text ons-u-vh">Completed: </span>
<span class="ons-panel__icon ons-u-fs-xl"><svg class="ons-icon ons-icon--xl" viewBox="0 0 13 10"
xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor" role="img" title="ons-icon-check">
<path
d="M14.35,3.9l-.71-.71a.5.5,0,0,0-.71,0h0L5.79,10.34,3.07,7.61a.51.51,0,0,0-.71,0l-.71.71a.51.51,0,0,0,0,.71l3.78,3.78a.5.5,0,0,0,.71,0h0L14.35,4.6A.5.5,0,0,0,14.35,3.9Z"
transform="translate(-1.51 -3.04)" />
</svg></span>
<div class="ons-panel__body ons-icon-margin--xl">
<h2 class="ons-u-fs-xl">xl</h2>
</div>
</div>
<div aria-labelledby="alert" role="alert" tabindex="-1" class="ons-panel ons-panel--success ons-panel--no-title"
id="success-id">
<span id="alert" class="ons-panel__assistive-text ons-u-vh">Completed: </span>
<span class="ons-panel__icon ons-u-fs-l"><svg class="ons-icon ons-icon--l" viewBox="0 0 13 10"
xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor" role="img" title="ons-icon-check">
<path
d="M14.35,3.9l-.71-.71a.5.5,0,0,0-.71,0h0L5.79,10.34,3.07,7.61a.51.51,0,0,0-.71,0l-.71.71a.51.51,0,0,0,0,.71l3.78,3.78a.5.5,0,0,0,.71,0h0L14.35,4.6A.5.5,0,0,0,14.35,3.9Z"
transform="translate(-1.51 -3.04)" />
</svg></span>
<div class="ons-panel__body ons-icon-margin--l">
<h2 class="ons-u-fs-l">l</h2>
</div>
</div>
<div aria-labelledby="alert" role="alert" tabindex="-1" class="ons-panel ons-panel--success ons-panel--no-title"
id="success-id">
<span id="alert" class="ons-panel__assistive-text ons-u-vh">Completed: </span>
<span class="ons-panel__icon ons-u-fs-m"><svg class="ons-icon ons-icon--m" viewBox="0 0 13 10"
xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor" role="img" title="ons-icon-check">
<path
d="M14.35,3.9l-.71-.71a.5.5,0,0,0-.71,0h0L5.79,10.34,3.07,7.61a.51.51,0,0,0-.71,0l-.71.71a.51.51,0,0,0,0,.71l3.78,3.78a.5.5,0,0,0,.71,0h0L14.35,4.6A.5.5,0,0,0,14.35,3.9Z"
transform="translate(-1.51 -3.04)" />
</svg></span>
<div class="ons-panel__body ons-icon-margin--m">
<h2 class="ons-u-fs-m">m</h2>
</div>
</div>
<div aria-labelledby="alert" role="alert" tabindex="-1" class="ons-panel ons-panel--success ons-panel--no-title"
id="success-id">
<span id="alert" class="ons-panel__assistive-text ons-u-vh">Completed: </span>
<span class="ons-panel__icon ons-u-fs-r"><svg class="ons-icon" viewBox="0 0 13 10" xmlns="http://www.w3.org/2000/svg"
focusable="false" fill="currentColor" role="img" title="ons-icon-check">
<path
d="M14.35,3.9l-.71-.71a.5.5,0,0,0-.71,0h0L5.79,10.34,3.07,7.61a.51.51,0,0,0-.71,0l-.71.71a.51.51,0,0,0,0,.71l3.78,3.78a.5.5,0,0,0,.71,0h0L14.35,4.6A.5.5,0,0,0,14.35,3.9Z"
transform="translate(-1.51 -3.04)" />
</svg></span>
<div class="ons-panel__body">
<p>r</p>
</div>
</div>
<div aria-labelledby="alert" role="alert" tabindex="-1" class="ons-panel ons-panel--success ons-panel--no-title"
id="success-id">
<span id="alert" class="ons-panel__assistive-text ons-u-vh">Completed: </span>
<span class="ons-panel__icon ons-u-fs-s"><svg class="ons-icon ons-icon--s" viewBox="0 0 13 10"
xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor" role="img" title="ons-icon-check">
<path
d="M14.35,3.9l-.71-.71a.5.5,0,0,0-.71,0h0L5.79,10.34,3.07,7.61a.51.51,0,0,0-.71,0l-.71.71a.51.51,0,0,0,0,.71l3.78,3.78a.5.5,0,0,0,.71,0h0L14.35,4.6A.5.5,0,0,0,14.35,3.9Z"
transform="translate(-1.51 -3.04)" />
</svg></span>
<div class="ons-panel__body ons-icon-margin--s">
<p class="ons-u-fs-s">s</p>
</div>
</div>Help improve this page
Let us know how we could improve this page, or share your user research findings. Discuss this page on GitHub (opens in a new tab)