Button

import { ... } from '@ag.ds-next/react/button';

<ButtonGroup>
	<Button variant="primary">Primary</Button>
	<Button variant="secondary">Secondary</Button>
	<Button variant="tertiary">Tertiary</Button>
</ButtonGroup>

A button communicates an action to a user and indicates what will happen next.

There are 3 visual button weights that convey their visual prominence: primary, secondary and tertiary.

Make sure you include a meaningful text label with or without an icon on a button.

Do

• left-align buttons from the most to least important action - right aligned buttons can be missed, especially on large screens or for screen magnifier users
• create a meaningful button label with a verb and a noun that makes the action obvious to all users - e.g. ‘Register establishment’
• avoid general labels that don’t provide full context. - e.g. ‘Click here’
• use the loading property to let users know their action is being processed
• customise the loadingLabel property announcement to make it more contextual
• add an icon if it helps users understand the action, and only in conjunction with a text label
• use only one Primary button on a page. You can use more than one Secondary or Tertiary button.

Don’t

• use a button if a user needs to go to another page – use a link or a link that looks like a button
• use an icon without a text label
• use disabled buttons as they can confuse users because they:
  • don’t tell users why the content is unavailable
  • are not keyboard accessible.
  • can be hard for users with a visual impairment to see.

Primary

A Primary button uses a solid background and is the most prominent button on a page. A single Primary button should be used for the main action a user needs to complete on a page or a critical call to action.

Some pages won’t have a primary action, instead they’ll have multiple secondary or tertiary actions.

Don’t include multiple Primary buttons on a page.

<Button variant="primary">Primary button</Button>

Secondary

A Secondary button has a clear background and solid border making it less prominent than a Primary button. Secondary buttons should be used for less important actions than the main action.

A Secondary button is often paired with a Primary button. Typically it performs the opposite action to the primary button.

You can use multiple Secondary buttons on a page.

<Button variant="secondary">Secondary button</Button>

Tertiary

A Tertiary button has no border or background to make it the least prominent button style. It is used for the least important actions on a page.

You can use multiple Tertiary buttons on a page.

<Button variant="tertiary">Tertiary button</Button>

Text

A Text button is styled like the Tertiary button but has no padding. A Text button should only be used in situations like tables where there is limited space.

You can use multiple Text buttons on a page.

<Button variant="text">Text button</Button>

Block

A Block button spans the full width of the container or parent element.

<Button type="submit" block>
	Submit
</Button>

Loading

Use the loading property to let users know their action is being processed.

<Button type="submit" loading>
	Submit
</Button>

Disabled

A user can’t interact with a disabled button. They are low contrast to indicate the user can’t take an action at that time in their journey which can cause issues for users with vision impairment.

Avoid using disabled buttons as they can be confusing for many users. Instead, allow users to interact with the button and receive feedback about why the action cannot be completed.

<ButtonGroup>
	<Button variant="primary" disabled>
		Primary
	</Button>
	<Button variant="secondary" disabled>
		Secondary
	</Button>
	<Button variant="tertiary" disabled>
		Tertiary
	</Button>
</ButtonGroup>

Icons

An icon can be used next to a meaningful text label in a button to help users quickly recognise what the button does.

Use icons that accurately communicate the label meaning and describe the action. For example, the search field button uses a magnifying glass icon because it is meaningful and universally understood to represent search actions.

The icon should appear before the text except when the icon indicates direction, e.g. Next or external links.

<ButtonLink href="/sign-out" iconBefore={AvatarIcon}>
	Sign out
</ButtonLink>

Links

You can style links to look like buttons to make them more prominent.

ButtonLink adopts the Link component from your chosen router framework, which you can set in the Core component.

<ButtonLink href="/sign-in">Sign in</ButtonLink>

Size

Size is a property that allows you to adjust the visual weight of a button.

The medium button should be used in most cases to provide a large click target.

<ButtonGroup>
	<Button variant="primary" size="sm">
		Primary
	</Button>
	<Button variant="secondary" size="sm">
		Secondary
	</Button>
	<Button variant="tertiary" size="sm">
		Tertiary
	</Button>
</ButtonGroup>

Colour

If a button sits inside an interface element that uses the light colour palette, make sure you use the light action colour for the button. If a button sits inside an interface element that uses the dark colour palette, make sure you use the dark action colour for the button.

Don’t draw attention to destructive actions like “delete” or “remove” by using red buttons. The colour red is reserved for errors.

<Box palette="dark" background="body" padding={1}>
	<ButtonGroup>
		<Button variant="primary">Primary</Button>
		<Button variant="secondary">Secondary</Button>
		<Button variant="tertiary">Tertiary</Button>
	</ButtonGroup>
</Box>

Button groups

For convenience, you can use all 3 button weights in a group side-by-side in a line.

On mobile, buttons will be stacked on top of one another and span the full width of a screen. This ensures they’re easily accessible by both left and right-handed users.

<ButtonGroup>
	<Button variant="primary">Primary</Button>
	<Button variant="secondary">Secondary</Button>
	<Button variant="tertiary">Tertiary</Button>
</ButtonGroup>

Focus ring

A button will receive a focus ring when navigated to via the keyboard. If you need to display a focus ring outside of these interactions, e.g. when navigating to a button via a link, use the focusRingFor prop.

<Stack alignItems="flex-start" gap={2}>
	<TextLink href="#focus-button-via-link">Focus the button</TextLink>

	<Button focusRingFor="all" id="focus-button-via-link">
		Upload
	</Button>
</Stack>

You can also programmatically focus a button using a ref.

() => {
	const ref = React.useRef(null);

	return (
		<Stack alignItems="flex-start" gap={2}>
			<Button onClick={() => ref.current.focus()} variant="secondary">
				Focus the button
			</Button>

			<Button focusRingFor="all" ref={ref}>
				Upload
			</Button>
		</Stack>
	);
};