Button

Examples

Primary

Primary buttons stand out the most and are used for the most important actions.

Code

1<Button variation="primary">Submit button</Button>

Secondary

Secondary buttons are still fairly prominent but are used for less important alternatives to the primary action.

Code

1<Button variation="secondary">Submit button</Button>

Tertiary

Tertiary buttons are used for ancillary actions such as viewing terms and conditions and are intentionally much less prominent.

Code

1<Button variation="tertiary">Submit button</Button>

Text

Text styled buttons are available when interactive functionality is required to be inline with paragraph text or other text regions.

Code

1<Button variation="text">Submit button</Button>

Pill

Selected state

Code

1<Button variation="pill" size="small">Submit button</Button>
2
3Selected state
4<Button className="selected" variation="pill" onClick={() => {}}>Submit button</Button>

Full width

Code

1<Button variation="primary" displayWidth="fullWidth">Submit button</Button>

Button sizes

Primary variation

(default)

Secondary variation

(default)

Tertiary variation

(default)

Text variation

(default)

Text Secondary variation

(default)

Pill variation

(default)

Code

1<Button variation="primary" size="small" onClick={() => {}}>Submit button</Button>
2<Button variation="primary" onClick={() => {}}>Submit button</Button>
3<Button variation="primary" size="large" onClick={() => {}}>Submit button</Button>
4<Button variation="primary" size="xlarge" onClick={() => {}}>Submit button</Button>
5
6<Button variation="secondary" size="small" onClick={() => {}}>Submit button</Button>
7<Button variation="secondary" onClick={() => {}}>Submit button</Button>
8<Button variation="secondary" size="large" onClick={() => {}}>Submit button</Button>
9<Button variation="secondary" size="xlarge" onClick={() => {}}>Submit button</Button>
10
11<Button variation="tertiary" size="small" onClick={() => {}}>Submit button</Button>
12<Button variation="tertiary" onClick={() => {}}>Submit button</Button>
13<Button variation="tertiary" size="large" onClick={() => {}}>Submit button</Button>
14<Button variation="tertiary" size="xlarge" onClick={() => {}}>Submit button</Button>
15
16<Button variation="text" size="small" onClick={() => {}}>Submit button</Button>
17<Button variation="text" onClick={() => {}}>Submit button</Button>
18<Button variation="text" size="large" onClick={() => {}}>Submit button</Button>
19<Button variation="text" size="xlarge" onClick={() => {}}>Submit button</Button>
20
21<Button variation="textSecondary" size="small" onClick={() => {}}>Submit button</Button>
22<Button variation="textSecondary" onClick={() => {}}>Submit button</Button>
23<Button variation="textSecondary" size="large" onClick={() => {}}>Submit button</Button>
24<Button variation="textSecondary" size="xlarge" onClick={() => {}}>Submit button</Button>
25
26<Button variation="pill" size="small" onClick={() => {}}>Submit button</Button>
27<Button variation="pill" onClick={() => {}}>Submit button</Button>
28<Button variation="pill" size="large" onClick={() => {}}>Submit button</Button>
29<Button variation="pill" size="xlarge" onClick={() => {}}>Submit button</Button>

Link

Link element Link element Link element Link element Link element

Code

1<Button variation="primary" href="/">Link element</Button>
2<Button variation="secondary" href="/">Link element</Button>
3<Button variation="tertiary" href="/">Link element</Button>
4<Button variation="text" href="/">Link element</Button>
5<Button variation="pill" href="/">Link element</Button>

Disabled

Code

1<Button variation="primary" disabled>Submit button</Button>
2<Button variation="secondary" disabled>Submit button</Button>
3<Button variation="tertiary" disabled>Submit button</Button>
4<Button variation="text" disabled>Submit button</Button>
5<Button variation="pill" onClick={() => {}} disabled>Submit button</Button>

Loading

Code

1<Button variation="primary" loading>Submit button</Button>
2<Button variation="secondary" loading>Submit button</Button>
3<Button variation="tertiary" loading>Submit button</Button>
4<Button variation="text" loading>Submit button</Button>

With an icon

Code

1<Button variation="primary">
2	Submit button
3	<PlusCircleIcon />
4</Button>
5
6<Button variation="primary">
7	<PlusCircleIcon />
8	Submit button
9</Button>

Design

Buttons were invented to submit forms only. As the web has evolved, so has the button. The button is still used to submit forms, but it is also used to initiate changes on a page, to set or select an option and to draw attention to key links such as start an application or buy now.

There are 3 visual hierarchies of primary, secondary and tertiary along with a text only, text secondary and pill versions:: Primary; Secondary; Tertiary; Text; Text Secondary; Pill

Problem

As a customer, I want to take an action or convey a decision. I need to clearly understand which action I am taking.
As a designer, I want to provide a series of options to a customer. I may want to biase the decsion of the customer, or leave the options un-weighted.

Solution

Display one or more buttons to allow the customer to take an action or make a decision. Use visual hierarchy to suggest the importance of the various alternatives.

Guidance

The primary button should stand out more than the secondary and the secondary more than the tertiary.
Use the primary button for the main call to action on a page.
Use a combination of the primary and secondary buttons where there is a choice and you wish to bias or influence the customer’s decision. For example ‘Apply’ and ‘Cancel’ where you wish the customer to apply.
Use a combination of 2 secondary buttons when you do not want to bias the customer.
Use the tertiary button for less important or common options. For example terms and conditions when applying or agreeing to something.
Use a tertiary button in preference to a secondary button, where the secondary action is destructive and you don't want users to tap it inadvertently
When used on a form, display the buttons at the end of the form and aligned to the left, with the primary button first and then the secondary buttons.
When used in a confined space such as a modal, display the buttons on the right, with the primary button on the far right and the secondary or tertiary to the left of the primary.
When used in a true wizard, or scenario where the user is likely to go forwards and backwards, use a primary button on the far right and a secondary back but on the far left.
Limit the use of primary buttons to 1 per page where possible.
Use buttons to highlight important links. Avoid generic labels such as ‘Click here’.
Use short, meaningful button labels
Use active descriptive verbs for your labels such as ‘Save’ or ‘Continue’.
Use sentence case for all button labels

Accessibility

Avoid the use of disabled buttons where possible, using validation instead to explain why the action cannot be taken.
Ensure contrast between button label and button background exceeds 4.5 to 1.
Ensure contrast between button background and the surface on which is sits exceeds 4.5 to 1.
Ensure there is a minimum contrast ratio of 3 to 1 between the default state of a button and the focused and hover states.
Provide developers with additional context to generic or repeat labels such as ‘Apply’, to be added in the code.
Ensure target size exceeds 24px by 24px

Avoiding disabled buttons

While styling is provided for disabled buttons other interactions should be considered first before applying disabled buttons, particularly to submittable forms.

Issues with disabled buttons:: A significant issue for assistive technology users.; They are hard to see for sighted users.; Users still attempt to click a disabled button due to its actionable words, this confuses users when no subsequent action occurs.; No feedback is provided to the user - that is for sighted mouse users, keyboard users and screen reader users.; Error handling becomes problematic.; They make users think and apply additional cognitive load.; Disabled buttons are removed from the focus order for keyboard users.

Alternatives to disabled buttons:: Relevant error validation that conveys why the button is disabled.; Read only content - output a paragraph or strong element instead.

Buttons or Links?

Button styles are available as both button elements or anchor elements, it is important to use the correct element based on the interaction.
While buttons and links can both be given similar visual treatments, it is important that a link is used for clicking an element that will navigate the user to a different page.
Buttons are for submitting forms or for interactions within in the current page.

Recommended usage for buttons:: Submitting forms; Interactions within the page; Opening modal windows; Toggling states like accordions or expandable menus

Recommended usage for links:: Interactions that redirect to another page.; Interactions that shift focus to a section within the current page - using the ID (#) reference.; Actions that open new windows or tabs.

Development

Import by:

1import { Button } from '@parsley_design_systems/design-system'

Available props

Props for the Button component
Property	Type	Default	Required	Description
children	ReactNode		true	The content to display in the button, this can be text or text with an Icon component.
variation	oneOf: primary \| secondary \| tertiary \| text \| textSecondary \| pill		true	Variation defines the button style.
size	oneOf: default \| small \| large \| xlarge	default	false	Sets the size of the element, this props controls the font size and padding of the form control. If not set "default" is output as the default setting.
className	string		false	Allows for specific classNames to be set.
onClick	function		true \| false	Fires the onClick event of the button or abchor element. For a button element the onClick event is required, for an anchor element it is optional as the href can solely be used instead.
element	a \| button	button	false	Renders a button or an anchor element, if not defined a button element is output by default.
href	string		true when element is an 'a'.	A href is required when setting the element type as an anchor (a), the value passed needs to be a URL string.
type	button, submit, reset	button	false	Sets the type of the button element, if not set "button" is output as the default setting.
displayWidth	oneOf: string \| array \| object - fullWidth \| wrap		wrap	Allows the width of the element to be full width or wrapping the element content. Wrapping the child content with assigned padding is the default setting.
gap	oneOf: default \| small \| large	default		Sets the space gap between button children.
borderWidth	small \| medium	medium		Sets the border width of the button
disabled	boolean		false	A boolean that turns the element into a disabled state.
loading	boolean		false	A boolean that adds a loading state to the element.
labelContext	string		false	Allows for additional instructions to be inserted into the element, this content is visually hidden and can be used to provide additional context to the element for assistive technolgy users.
ref	string		false	Allows a ref to be set on the button \| link.