Button
- Central CMS
- Central Forms
- Central Connect
Pulsar buttons are an all purpose user interface element allowing users to perform actions, submit forms and progress through transactions.
Basic usage
- Twig
- React
- HTML
{{
html.button({
'label': 'My Action'
})
}}
<Button>My Action</Button>
<button class="btn">My Action</button>
Helper options
You can configure this helper using the common helper options, the following options are specific to this helper.
Option | Type | Description |
---|---|---|
type | string | Type 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:
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
.
- Twig
- React
- HTML
{{
html.button({
'label': html.icon('plus', { 'label': 'Add to list' })
})
}}
{{
html.button({
'label': html.icon('plus'),
'aria-label': 'Add to list'
})
}}
<Button className="btn">
<i className="icon-plus">
<span className="hide">Add to list</span>
</i>
</Button>
<Button className="btn" aria-label="Add to list">
<i className="icon-plus"></i>
</Button>
<button class="btn">
<i class="icon-plus">
<span class="hide">Add to list</span>
</i>
</button>
<button class="btn" aria-label="Add to list">
<i class="icon-plus"></i>
</button>
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
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 bothenter
andspace
, but regular links will not
Link button
- Twig
- React
- HTML
{{
html.button({
'label': 'Next',
'class': 'btn--primary',
'type': 'link',
'href': '/path/to/destination'
})
}}
<Button
className="btn btn--primary"
type="link"
href="/path/to/destination">Next</Button>
<a class="btn btn--primary" href="/path/to/destination">Next</a>
Input button
Only for use within forms, and you should have a really good reason not to use a regular button
.
- Twig
- React
- HTML
{{
html.button({
'label': 'Add Keyword',
'type': 'input'
})
}}
<Button type="input">Add Keyword</Button>
<input type="button" value="Add Keyword" class="btn" />
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.
- Twig
- React
- HTML
{{
html.button({
'label': 'Submit',
'type': 'submit'
})
}}
<Button type="submit">Submit</Button>
<input type="submit" class="btn">Submit</input>
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
orsubmit
type, add thedisabled
attribute - if using
link
type, add thearia-disabled="true"
attribute
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.
- Twig
- React
- HTML
<div data-tippy-content="Can’t touch this" tabindex="0" class="u-display-inline-block">
{{
html.button({
'label': 'Disabled Button',
'disabled': true
})
}}
</div>
<div data-tippy-content="Can’t touch this" tabIndex="0" className="u-display-inline-block">
<Button disabled>Disabled Button</Button>
</div>
<div data-tippy-content="Can’t touch this" tabindex="0" class="u-display-inline-block">
<button disabled="disabled" class="btn is-disabled">Disabled Button</button>
</div>