Use up and down keys to navigate results once you've typed more than two characters. Use the enter key to select a result. Touch device users, explore by touch or with swipe gestures.
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.
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.
{% 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
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 }
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
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 }
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”.