Button

Overview

Use a button to help users perform an action, such as to submit a form or dynamically add, remove, show or hide something on a page using Javascript.

When not to use this component

Example Button contents

Nunjucksfor Example Button
Nunjucks macro optionsfor Example Button
HTMLfor Example Button

Nunjucks

{% from "components/button/_macro.njk" import onsButton %}
{{
    onsButton({
        "text": "Save and continue"
    })
}}

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="submit" class="ons-btn">
  <span class="ons-btn__inner"><span class="ons-btn__text">Save and continue</span></span>
</button>

Buttons should not be used for navigation purposes, instead use links.

How to use this component

Write button text in sentence case, describing the action it performs.

The button label should be short, clear and direct. For example ‘Save and continue’ or ‘Sign in’.

When using more than one button on a page, be careful not to duplicate the text inside the button as this will cause accessibility issues for non-visual users.

If you have to duplicate text for visual consistency, use buttonContext to set visually hidden context for screen readers.

Align the primary action button to the left side of a form.

Primary (default)

Use a primary button for the main call to action on a page.

Important information:

Avoid using multiple primary buttons on the same page. This will reduce the impact and make it hard for users to know what to do next.

Nunjucks

{% from "components/button/_macro.njk" import onsButton %}
{{
    onsButton({
        "text": "Save and continue"
    })
}}

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="submit" class="ons-btn">
  <span class="ons-btn__inner"><span class="ons-btn__text">Save and continue</span></span>
</button>

Variants

To use an alternative type of button, set the variants parameter to either a single value or an array of multiple values, such as "variants": 'small' or "variants": ['small', 'secondary'].

Small

This variant can be used when space and layout dictates.

In certain circumstances there may be the need for multiple primary actions to exist on a page. The small primary button should also be used in this scenario.

However, using multiple primary buttons is only appropriate when showing a parallel set of objects with the same level of priority.

Using "variants": 'small' will style the button appropriately.

Example Button Small contents

Nunjucksfor Example Button Small
Nunjucks macro optionsfor Example Button Small
HTMLfor Example Button Small

Nunjucks

{% from "components/button/_macro.njk" import onsButton %}
{{
    onsButton({
        "type": 'button',
        "text": 'Add',
        "variants": 'small'
    })
}}

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--small">
  <span class="ons-btn__inner"><span class="ons-btn__text">Add</span></span>
</button>

Secondary

Use secondary buttons in combination with a primary button for secondary actions on the page.

Important information:

Avoid using too many secondary buttons on the same page as it can make it hard for users to know what to do next

Using "variants": 'secondary' will style the button appropriately.

Example Button Secondary contents

Nunjucksfor Example Button Secondary
Nunjucks macro optionsfor Example Button Secondary
HTMLfor Example Button Secondary

Nunjucks

{% from "components/button/_macro.njk" import onsButton %}
{{
    onsButton({
        "type": 'button',
        "text": 'Add a person',
        "variants": '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--secondary">
  <span class="ons-btn__inner"><span class="ons-btn__text">Add a person</span></span>
</button>

Secondary (small)

A small secondary button should be used within the same context of a primary small button when there is an additional action available along with the primary action.

Using "variants": ['secondary', ‘small’] will style the button appropriately.

Example Button Secondary Small contents

Nunjucksfor Example Button Secondary Small
Nunjucks macro optionsfor Example Button Secondary Small
HTMLfor Example Button Secondary Small

Nunjucks

{% from "components/button/_macro.njk" import onsButton %}
{{
    onsButton({
        "type": 'button',
        "text": 'Add',
        "variants": ['secondary', 'small']
    })
}}

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--secondary ons-btn--small">
  <span class="ons-btn__inner"><span class="ons-btn__text">Add</span></span>
</button>

Call to action

The call to action variant should only be used when a link to a new page is the primary call to action on a page. For example, a “Start survey” link.

Links simply styled as buttons are not accessible to users who navigate a web page with voice commands or a keyboard. Setting url will add the attribute role="button" and use Javascript to help these users select the link.

Example Button Link contents

Nunjucksfor Example Button Link
Nunjucks macro optionsfor Example Button Link
HTMLfor Example Button Link

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>

Call to action opening in a new tab or window

You can use this variant when a page needs to open in a new tab or window, for example, for a web chat service.

Using "newWindow": ‘true’ adds a warning for screen reader users (set by "newWindowDescription") to let them know a new tab or window will open. This helps screen reader users understand why the back button in the browser is disabled on the new page.

Example Button New Window contents

Nunjucksfor Example Button New Window
Nunjucks macro optionsfor Example Button New Window
HTMLfor Example Button New Window

Nunjucks

{% from "components/button/_macro.njk" import onsButton %}
{{
    onsButton({
        "text": 'Web chat',
        "url": '/patterns/send-a-web-form/examples/form/',
        "newWindow": true,
        "newWindowDescription": 'opens in a new window',
        "attributes": {
            "onclick": "window.open(this.href,'targetWindow','toolbar=no,location=no,status=no,menubar=no,scrollbars=yes,resizable=yes,width=360,height=680'); return false;"
        }
    })
}}

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="/patterns/send-a-web-form/examples/form/" role="button" class="ons-btn ons-btn--link ons-js-submit-btn"
  target="_blank" rel="noopener"
  onclick="window.open(this.href,&#39;targetWindow&#39;,&#39;toolbar=no,location=no,status=no,menubar=no,scrollbars=yes,resizable=yes,width=360,height=680&#39;); return false;">
  <span class="ons-btn__inner"><span class="ons-btn__text">Web chat</span><svg class="ons-icon ons-u-ml-2xs"
      viewBox="0 0 12 12" xmlns="http://www.w3.org/2000/svg" focusable="false" aria-hidden="true" role="img"
      title="ons-icon-external-link">
      <path
        d="M13.5,9H13a.5.5,0,0,0-.5.5v3h-9v-9h3A.5.5,0,0,0,7,3V2.5A.5.5,0,0,0,6.5,2h-4a.5.5,0,0,0-.5.5v11a.5.5,0,0,0,.5.5h11a.5.5,0,0,0,.5-.5v-4A.5.5,0,0,0,13.5,9Z"
        transform="translate(-2 -1.99)" />
      <path
        d="M8.83,7.88a.51.51,0,0,0,.71,0l2.31-2.32,1.28,1.28A.51.51,0,0,0,14,6.49v-4a.52.52,0,0,0-.5-.5h-4A.51.51,0,0,0,9,2.52a.58.58,0,0,0,.14.33l1.28,1.28L8.12,6.46a.51.51,0,0,0,0,.71Z"
        transform="translate(-2 -1.99)" />
    </svg></span>
  <span class="ons-btn__new-window-description ons-u-vh">(opens in a new window)</span>
</a>

Ghost

Use this variant when a page needs to open in a new tab or window, for example, for a web chat service.

Using "newWindow": ‘true’ adds a warning for screen reader users (set by "newWindowDescription") to let them know a new tab or window will open when they select the button. This helps screen reader users understand why the back button in the browser is disabled on the new page.

Example Button Ghost contents

Nunjucksfor Example Button Ghost
Nunjucks macro optionsfor Example Button Ghost
HTMLfor Example Button Ghost

Nunjucks

{% from "components/button/_macro.njk" import onsButton %}
<div style="padding: 1.5rem; background: #206095">
    {{
        onsButton({
            "text": 'Save and sign out',
            "url": '#0',
            "variants": 'ghost',
            "iconType": "exit",
            "iconPosition": "after"
        })
    }}
</div>

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

<div style="padding: 1.5rem; background: #206095">
  <a href="#0" role="button" class="ons-btn ons-btn--ghost ons-btn--link ons-js-submit-btn">
    <span class="ons-btn__inner"><span class="ons-btn__text">Save and sign out</span><svg class="ons-icon ons-u-ml-2xs"
        viewBox="0 0 12 12" xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor" role="img"
        title="ons-icon-exit">
        <path
          d="M13.85,7.65l-2.5-2.5a.5.5,0,0,0-.71,0,.48.48,0,0,0-.15.36V7h-3a.5.5,0,0,0-.5.5v1a.5.5,0,0,0,.5.5h3v1.5A.49.49,0,0,0,11,11a.48.48,0,0,0,.34-.14l2.51-2.5a.49.49,0,0,0,0-.68Z"
          transform="translate(-2 -2)" />
        <path
          d="M8.5,14h-6a.5.5,0,0,1-.5-.5V2.5A.5.5,0,0,1,2.5,2h6a.5.5,0,0,1,.5.5V3a.5.5,0,0,1-.5.5h-5v9h5A.5.5,0,0,1,9,13v.5A.5.5,0,0,1,8.5,14Z"
          transform="translate(-2 -2)" />
      </svg></span>
  </a>
</div>

Disabled

Disabled buttons have poor contrast and can confuse some users.

Warning:

Only use disabled buttons if research shows it makes the page easier to understand

For example, the “Send message” button in the send and reply to messages pattern is disabled until a message is entered into the field immediately before it.

Using "variants": ‘disabled’ will style the button and add the HTML disabled attribute.

Example Button Disabled contents

Nunjucksfor Example Button Disabled
Nunjucks macro optionsfor Example Button Disabled
HTMLfor Example Button Disabled

Nunjucks

{% from "components/button/_macro.njk" import onsButton %}
{{
    onsButton({
        "text": 'Submit',
        "variants": 'disabled'
    })
}}

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="submit" class="ons-btn ons-btn--disabled" disabled>
  <span class="ons-btn__inner"><span class="ons-btn__text">Submit</span></span>
</button>

Loader

The loader button should be used when the button starts a process that can take longer than expected to complete.

Using "variants": ‘loader’ will display an animated loading icon and disable the button to prevent a form being submitted more than once if a user tries to select the button multiple times.

Example Button Loader contents

Nunjucksfor Example Button Loader
Nunjucks macro optionsfor Example Button Loader
HTMLfor Example Button Loader

Nunjucks

{% from "components/button/_macro.njk" import onsButton %}
<form onsubmit="return false;">
    {{
        onsButton({
            "text": 'Submit',
            "variants": 'loader'
        })
    }}
</form>

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

<form onsubmit="return false;">
  <button type="submit" class="ons-btn ons-btn--loader ons-btn--loader ons-js-loader ons-js-submit-btn">
    <span class="ons-btn__inner"><span class="ons-btn__text">Submit</span><svg class="ons-icon ons-u-ml-2xs"
        xmlns="http://www.w3.org/2000/svg" focusable="false" viewBox="0 0 100 100" preserveAspectRatio="xMidYMid"
        fill="currentcolor" role="img" title="ons-icon-loader">
        <rect x="0" y="0" width="100" height="100" fill="none"></rect>
        <rect x="46.5" y="40" width="7" height="20" rx="5" ry="5" transform="rotate(0 50 50) translate(0 -30)">
          <animate attributeName="opacity" from="1" to="0" dur="1s" begin="0s" repeatCount="indefinite" />
        </rect>
        <rect x="46.5" y="40" width="7" height="20" rx="5" ry="5" transform="rotate(30 50 50) translate(0 -30)">
          <animate attributeName="opacity" from="1" to="0" dur="1s" begin="0.08333333333333333s"
            repeatCount="indefinite" />
        </rect>
        <rect x="46.5" y="40" width="7" height="20" rx="5" ry="5" transform="rotate(60 50 50) translate(0 -30)">
          <animate attributeName="opacity" from="1" to="0" dur="1s" begin="0.16666666666666666s"
            repeatCount="indefinite" />
        </rect>
        <rect x="46.5" y="40" width="7" height="20" rx="5" ry="5" transform="rotate(90 50 50) translate(0 -30)">
          <animate attributeName="opacity" from="1" to="0" dur="1s" begin="0.25s" repeatCount="indefinite" />
        </rect>
        <rect x="46.5" y="40" width="7" height="20" rx="5" ry="5" transform="rotate(120 50 50) translate(0 -30)">
          <animate attributeName="opacity" from="1" to="0" dur="1s" begin="0.3333333333333333s"
            repeatCount="indefinite" />
        </rect>
        <rect x="46.5" y="40" width="7" height="20" rx="5" ry="5" transform="rotate(150 50 50) translate(0 -30)">
          <animate attributeName="opacity" from="1" to="0" dur="1s" begin="0.4166666666666667s"
            repeatCount="indefinite" />
        </rect>
        <rect x="46.5" y="40" width="7" height="20" rx="5" ry="5" transform="rotate(180 50 50) translate(0 -30)">
          <animate attributeName="opacity" from="1" to="0" dur="1s" begin="0.5s" repeatCount="indefinite" />
        </rect>
        <rect x="46.5" y="40" width="7" height="20" rx="5" ry="5" transform="rotate(210 50 50) translate(0 -30)">
          <animate attributeName="opacity" from="1" to="0" dur="1s" begin="0.5833333333333334s"
            repeatCount="indefinite" />
        </rect>
        <rect x="46.5" y="40" width="7" height="20" rx="5" ry="5" transform="rotate(240 50 50) translate(0 -30)">
          <animate attributeName="opacity" from="1" to="0" dur="1s" begin="0.6666666666666666s"
            repeatCount="indefinite" />
        </rect>
        <rect x="46.5" y="40" width="7" height="20" rx="5" ry="5" transform="rotate(270 50 50) translate(0 -30)">
          <animate attributeName="opacity" from="1" to="0" dur="1s" begin="0.75s" repeatCount="indefinite" />
        </rect>
        <rect x="46.5" y="40" width="7" height="20" rx="5" ry="5" transform="rotate(300 50 50) translate(0 -30)">
          <animate attributeName="opacity" from="1" to="0" dur="1s" begin="0.8333333333333334s"
            repeatCount="indefinite" />
        </rect>
        <rect x="46.5" y="40" width="7" height="20" rx="5" ry="5" transform="rotate(330 50 50) translate(0 -30)">
          <animate attributeName="opacity" from="1" to="0" dur="1s" begin="0.9166666666666666s"
            repeatCount="indefinite" />
        </rect>
      </svg></span>
  </button>
</form>

Timer

The timer button can be used to prevent forms being submitted twice when users double-click the submit button without displaying the animated loading icon.

Using "variants": ‘timer’ will disable the button for one second after it’s selected.

Example Button Timer contents

Nunjucksfor Example Button Timer
Nunjucks macro optionsfor Example Button Timer
HTMLfor Example Button Timer

Nunjucks

{% from "components/button/_macro.njk" import onsButton %}
<form onsubmit="return false;">
    {{
        onsButton({
            "text": 'Submit',
            "variants": 'timer'
        })
    }}
</form>

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

<form onsubmit="return false;">
  <button type="submit" class="ons-btn ons-btn--timer ons-js-timer ons-js-submit-btn">
    <span class="ons-btn__inner"><span class="ons-btn__text">Submit</span></span>
  </button>
</form>

Print

Using "variants": ‘print’ will show a button with a print icon and add classes used in the print-button.js file.

The button will not show until the JavaScript has run, and will not be shown on a printed page.

Example Button Print contents

Nunjucksfor Example Button Print
Nunjucks macro optionsfor Example Button Print
HTMLfor Example Button Print

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>

Download

Using "variants": ‘download’ will show a button with a download icon and add the download attribute to make the browser save the file at the specified url.

Example Button Download contents

Nunjucksfor Example Button Download
Nunjucks macro optionsfor Example Button Download
HTMLfor Example Button Download

Nunjucks

{% from "components/button/_macro.njk" import onsButton %}
{{
    onsButton({
        "text": 'Save answers as PDF',
        "url": '#0',
        "variants": ['download', 'small', 'secondary'],
        "removeDownloadAttribute": true
    })
}}

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--download ons-btn--small ons-btn--secondary ons-btn--link ons-js-submit-btn">
  <span class="ons-btn__inner"><svg class="ons-icon ons-u-mr-2xs" viewBox="0 0 12 12" xmlns="http://www.w3.org/2000/svg"
      focusable="false" fill="currentColor" role="img" title="ons-icon-download">
      <path
        d="M5.6 9a.48.48 0 0 0 .7 0l3-3.2a.48.48 0 0 0 0-.7C9.3 5 9.2 5 9 5H7.5V.5A.47.47 0 0 0 7 0H5a.47.47 0 0 0-.5.5V5H3a.47.47 0 0 0-.5.5.37.37 0 0 0 .1.3Z" />
      <path
        d="M11.5 9H11a.47.47 0 0 0-.5.5v1h-9v-1A.47.47 0 0 0 1 9H.5a.47.47 0 0 0-.5.5v2a.47.47 0 0 0 .5.5h11a.47.47 0 0 0 .5-.5v-2a.47.47 0 0 0-.5-.5Z" />
    </svg><span class="ons-btn__text">Save answers as PDF</span></span>
</a>

Custom icon buttons

You can add an icon to a button using the parameters iconType and iconPosition.

Before adding an icon, see our guidance on using icons.

Example Button Custom contents

Nunjucksfor Example Button Custom
Nunjucks macro optionsfor Example Button Custom
HTMLfor Example Button Custom

Nunjucks

{% from "components/button/_macro.njk" import onsButton %}

<div class="ons-u-mb-l">
    {{
        onsButton({
            "type": 'button',
            "text": 'Done',
            "iconType": 'check'
        })
    }}
</div>
<div>
    {{
        onsButton({
            "text": 'Search',
            "iconType": 'search',
            "variants": ['secondary', 'small']
        })
    }}
</div>

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

<div class="ons-u-mb-l">
  <button type="button" class="ons-btn">
    <span class="ons-btn__inner"><svg class="ons-icon ons-u-mr-2xs" 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 class="ons-btn__text">Done</span></span>
  </button>
</div>
<div>
  <button type="submit" class="ons-btn ons-btn--secondary ons-btn--small">
    <span class="ons-btn__inner"><svg class="ons-icon ons-u-mr-2xs" viewBox="0 0 12 12"
        xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" role="img" title="ons-icon-search">
        <path
          d="M11.86 10.23 8.62 6.99a4.63 4.63 0 1 0-6.34 1.64 4.55 4.55 0 0 0 2.36.64 4.65 4.65 0 0 0 2.33-.65l3.24 3.23a.46.46 0 0 0 .65 0l1-1a.48.48 0 0 0 0-.62Zm-5-3.32a3.28 3.28 0 0 1-2.31.93 3.22 3.22 0 1 1 2.35-.93Z" />
      </svg><span class="ons-btn__text">Search</span></span>
  </button>
</div>

Grouping buttons

Use a button group when you need to place buttons together.

This lets you show a primary action, such as “Save and continue”, next to a secondary action, such as “Save as draft”.

Example Button Group contents

Nunjucksfor Example Button Group
Nunjucks macro optionsfor Example Button Group
HTMLfor Example Button Group

Nunjucks

{% from "components/button/_macro.njk" import onsButton %}

<div class="ons-btn-group">
    {{
        onsButton({
            "text": 'Continue'
        })
    }}
    {{
        onsButton({
            "type": 'button',
            "text": 'Cancel',
            "name": 'example',
            "variants": 'secondary'
        })
    }}
</div>

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

<div class="ons-btn-group">
  <button type="submit" class="ons-btn">
    <span class="ons-btn__inner"><span class="ons-btn__text">Continue</span></span>
  </button>
  <button type="button" class="ons-btn ons-btn--secondary" name="example">
    <span class="ons-btn__inner"><span class="ons-btn__text">Cancel</span></span>
  </button>
</div>

Help improve this page

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

Cookies on ons.gov.uk

Button

Overview

When not to use this component

Example Button contents

Nunjucks

Nunjucks macro options

HTML

How to use this component

Primary (default)

Example Button contents

Nunjucks

Nunjucks macro options

HTML

Variants

Small

Example Button Small contents

Nunjucks

Nunjucks macro options

HTML

Secondary

Example Button Secondary contents

Nunjucks

Nunjucks macro options

HTML

Secondary (small)

Example Button Secondary Small contents

Nunjucks

Nunjucks macro options

HTML

Call to action

Example Button Link contents

Nunjucks

Nunjucks macro options

HTML

Call to action opening in a new tab or window

Example Button New Window contents

Nunjucks

Nunjucks macro options

HTML

Ghost

Example Button Ghost contents

Nunjucks

Nunjucks macro options

HTML

Disabled

Example Button Disabled contents

Nunjucks

Nunjucks macro options

HTML

Loader

Example Button Loader contents

Nunjucks

Nunjucks macro options

HTML

Timer

Example Button Timer contents

Nunjucks

Nunjucks macro options

HTML

Print

Example Button Print contents

Nunjucks

Nunjucks macro options

HTML

Download

Example Button Download contents

Nunjucks

Nunjucks macro options

HTML

Custom icon buttons

Example Button Custom contents

Nunjucks

Nunjucks macro options

HTML

Grouping buttons

Example Button Group contents

Nunjucks

Nunjucks macro options

HTML