On this page

CTA Button

Trigger actions on the current page.

Overview
Rules and guidance
Properties
Styles
Accessibility

When to use

To trigger an action that happens on the current page, such as submitting a form, saving changes, or confirming a decision
As the primary call to action in a section or page
To confirm or cancel a destructive operation

When not to use

To navigate to another URL - use CTA Link instead. Buttons trigger actions; links go somewhere.
For inline text actions within a paragraph - use Text Link instead. A button in running text disrupts reading flow.

Anatomy

Button label: descriptor of the action that will be performed when pressed, for example "Submit"
Icon left: icon to the left of the text label to improve understanding and functionality
Icon right: icon to the right of the text label to improve understanding and functionality
Icon only: icon used on the button without a visible text label
Icon only text label: accompanying text label visible on hover and focus

Basic usage

Edit live code

<CTAButton variant="primary">Plant a Tree</CTAButton>

Variants and features

Primary

Use for the main action on a page or in a section. There should be at most one primary button per section.

Edit live code

<PrimaryCTAButton>Plant a Tree</PrimaryCTAButton>

Secondary

Use for supporting actions that sit alongside a primary button, such as "Cancel" next to "Save", or "Back" next to "Next".

Edit live code

<SecondaryCTAButton>Tell me more about trees</SecondaryCTAButton>

Tertiary

Use for low-emphasis actions that are available but not the focus of the page, such as an optional link to further reading or a secondary escape route alongside a primary and secondary button pair.

Edit live code

<TertiaryCTAButton>Skip for now</TertiaryCTAButton>

Destructive

Use when the action is irreversible, such as deleting an account, removing a payment method, or cancelling a service. This variant signals to the user that the action carries significant consequences.

Use the filled variant (DestructiveCTAButton) for a single high-prominence destructive action. Use the outlined variant (DestructiveSecondaryCTAButton) when the destructive action sits alongside another button. Use the low-emphasis variant (DestructiveTertiaryCTAButton) when the destructive action needs to be available but not visually dominant.

Edit live code

<DestructiveCTAButton>Delete account</DestructiveCTAButton>

Edit live code

<DestructiveSecondaryCTAButton>Cancel service</DestructiveSecondaryCTAButton>

Edit live code

<DestructiveTertiaryCTAButton>Remove payment method</DestructiveTertiaryCTAButton>

Icons

Add an icon to the left or right of the label to reinforce meaning. Use iconLeft for icons that categorise or contextualise the action, and iconRight for icons that indicate direction or continuation.

A right-pointing chevron (iconRight="chevron-right") signals that the journey continues on the next step rather than completing. Use it consistently across multi-step flows.

Edit live code

<PrimaryCTAButton iconRight="chevron-right">Next</PrimaryCTAButton>

Edit live code

<SecondaryCTAButton iconLeft="download">Download report</SecondaryCTAButton>

Icon only

Use the icon prop to show an icon instead of a label, for compact contexts such as a table row or toolbar. The children become the button's tooltip and accessible name, so always provide them.

icon takes precedence over iconLeft and iconRight, which are ignored. It has no effect on the primary and destructive variants, so use a secondary or tertiary variant.

Edit live code

<Cluster spaceBetween={2}>
  <ClusterItem>
    <SecondaryCTAButton icon="edit">Edit meter reading</SecondaryCTAButton>
  </ClusterItem>
  <ClusterItem>
    <TertiaryCTAButton icon="delete">Delete meter reading</TertiaryCTAButton>
  </ClusterItem>
</Cluster>

Full width

The fullWidth prop controls how the button sizes to its container:

'small' (default): full width below the smallest breakpoint, auto width above
'always': full width at all breakpoints
'never': always auto width

Edit live code

<PrimaryCTAButton fullWidth="always">Save changes</PrimaryCTAButton>

Small size

Use size="small" for compact contexts such as table rows, chips, or dense UI where the default button height (space.9) would be too large. The small variant uses space.6 height.

Edit live code

<PrimaryCTAButton size="small">Save</PrimaryCTAButton>

Loading state

Set loading to true when an async action is in progress. The button replaces its label with a spinner and becomes disabled automatically. Do not re-enable the button manually while it is in the loading state.

Edit live code

<PrimaryCTAButton loading={true}>Save</PrimaryCTAButton>

Content guidance

Write button labels that describe exactly what happens when the button is pressed. Vague labels like "OK" or "Yes" make users pause to remember what they agreed to.

Use sentence case: "Save changes", not "Save Changes"
Use active language: start with a verb that describes the outcome ("Submit", "Download report", "Delete account")
Each button on a page should have a unique label. If two buttons do the same thing in different contexts, add visually hidden text to distinguish them for screen reader users
Avoid possessive pronouns: "Save account details" rather than "Save my account details"
Use a right chevron icon to signal that the journey continues across steps, not that the action completes

Common patterns:

Context	Label
Form submission	"Save changes", "Submit"
Multi-step flow	"Next", "Save & continue"
Destructive confirmation	"Delete account", "Cancel service"
Dismissal	"Cancel", "Go back"