Skip to main content

Button

Pulsar buttons are an all purpose user interface element allowing users to perform actions, submit forms and progress through transactions.

Basic usage​

{{
    html.button({
        'label': 'My Action'
    })
}}

Helper options​

You can configure this helper using the common helper options, the following options are specific to this helper.

OptionTypeDescription
typestringType of button to create, can be button (default), link, input or submit

Accessibility​

Refer to the Jadu Accessibility Guidelines (internal) for detailed guidance on the accessibility requirements of this component.

Labelling your button​

The text label you use for a button should be clear enough for any user to understand what will happen if the user clicks the button, don't rely on colour alone to indicate whether this is a primary or dangerous action, the label is the most important piece of information.

If the button relates to an action, the label should ideally be a verb, use the common state classes to reinforce dangerous or destructive actions with colour, but don't rely on colour alone to communicate a button’s intention.

Other recommendations for labelling your buttons include:

Do use title case
Don’t use sentence case or all caps
Do use a text only label for primary actions, unless explicitly required for the UI
Don’t add icons to primary actions

If an action relates to creating new items of content, use 'New', Do not use 'Create' or 'Create New'.

If a button triggers more than one action you should communicate the chain of events to the user, ideally in the order in which they will happen. This helps users to build a mental model of what is happening when they push a button.

Using icons​

If your button is labelled using only an icon, you must supply an appropriate descriptive label to be announced by screenreaders, either by the icon's label option, or using aria-label.

 
{{
    html.button({
        'label': html.icon('plus', { 'label': 'Add to list' })
    })
}}

{{
    html.button({
        'label': html.icon('plus'),
        'aria-label': 'Add to list'
    })
}}

Button types​

The underlying HTML element you use for a button is an important choice, particularly for accessibility reasons, and your choice will usually be based on the type of action you wish to perform. In most cases this can usually be determined by this simple rule:

  • if the button goes somewhere, it should be a link
  • if the button does something, it should be a button
Accessibility tip

If you absolutely have to use a link for a button that does something, you should add the following affordances:

  • add the aria-role="button" attribute to make the element announce itself as a button rather than a link
  • add a javascript event handler to be triggered when the user presses the space key, as regular buttons will be triggered on both enter and space, but regular links will not
{{
    html.button({
        'label': 'Next',
        'class': 'btn--primary',
        'type': 'link',
        'href': '/path/to/destination'
    })
}}

Input button​

Only for use within forms, and you should have a really good reason not to use a regular button.

{{
    html.button({
        'label': 'Add Keyword',
        'type': 'input'
    })
}}

Submit button​

Should only be used to submit forms, if you're building a Pulsar styled form you can use standard submit controls with the form end component.

{{
    html.button({
        'label': 'Submit',
        'type': 'submit'
    })
}}

Disabled buttons​

If an action is unavailable you can disable the button, the common .is-disabled class will visually style the disabled state.

If you're not using the Twig or React helpers, you must make sure the following is applied to your button when disabled:

  • if using button, input or submit type, add the disabled attribute
  • if using link type, add the aria-disabled="true" attribute
Accessibility tip

Disabled buttons cannot be focused with the keyboard so will be invisible to screenreaders, this behaviour may be desired, or you may need to choose another UI pattern if you feel screenreader users need to always be aware that a button is present. Consider your use cases carefully.

Adding tooltips to disabled buttons​

The disabled attribute prevents mouse events from firing and stops tooltips from working entirely, the only way around this which works for all our supported browsers is to wrap the button in a containing div and attach the tooltip to that element.

<div data-tippy-content="Can’t touch this" tabindex="0" class="u-display-inline-block">
  {{ 
    html.button({
      'label': 'Disabled Button',
      'disabled': true
    })
  }}
</div>