Variants allow you to alter the visual prominence of a button. The variant prop accepts either solid, ghost, soft or transparent. When no variant is specified, the button will appear as ghost by default.When selecting a variant:
Choose a variant that reflects the importance of the action.
Avoid grouping buttons of the same variant, and instead create visual hierarchy using different variants.
Avoid using transparent buttons in isolation, as they offer less visual affordance on their own (consider using a TextLink instead).
Tones allow you to provide additional information regarding the meaning or importance of an action. The tone prop accepts either brandAccent, formAccent, critical or neutral. When no tone is specified, the button will appear as neutral by default.
brandAccent
For hero actions that want to leverage the brand colour, you can set the button’s tone to brandAccent. This is our most visibly strong tone and should be used sparingly.Use brandAccent to draw attention to our products most important actions, such as:
starting a key flow like apply or job posting
submitting a form or payment
submitting a primary search query (such as a new job or candidate search).
Avoid using multiple brandAccent buttons on the same page.
For cases where actions need to be emphasized, the tone can be set to formAccent. This is our second most visibly strong tone and can be used to emphasize an action. Unlike brandAccent, you may choose to have multiple formAccent buttons on the same page.
For destructive actions like “Delete” you can set the button’s tone to critical. This tone provides a visual warning to users and should be reserved for high risk actions.Avoid using multiple critical buttons in the same group of buttons. Multiple critical buttons may appear on the same page but should relate to different pieces of content.
For cases where actions need to be de-emphasized, the tone can be set to neutral. This makes the button follow the default text colour, including inverting on dark surfaces to improve contrast.
By default, a button has a neutral tone and uses the ghost variant, allowing the visual prominence to be increased or decreased as required.This enables colour to be applied as accents and with purpose, rather than by default — improving the management of user attention and supporting a more declarative hierarchy of actions.
Default is a neutral tone and ghost variant
To compliment this, when a tone is purposefully applied to a button, the default variant becomes solid to maximise its impact — allowing the visual prominence to be reduced as needed.
Default variant becomes solid when a tone is applied
The ghost, soft, and transparent variants automatically lighten their foreground colour to improve contrast against a dark background. To compliment this, the hover and active backgrounds remove the colour in favour of a white translucency.
Buttons with a neutral tone are inverted to improve contrast.
When using custom background colours or images on a Box component, this behaviour can be applied by setting the background to either customLight or customDark.
By default, buttons have no layout applied and run full width. We recommend positioning buttons side by side and sized to their content on tablet and desktop. On mobile, buttons should stack vertically at full width.The easiest way to achieve this layout is with the Actions component, which handles spacing and responsive behavior automatically. If you have specific layout needs, you can also use Inline or Columns.
When grouping buttons it’s important to create hierarchy by assigning different variants. Consider which action is the most important and give that button the most prominent appearance.A few examples of button groups that provide appropriate hierarchy are shown below.
Avoid displaying multiple solid buttons together with different tones applied. If you need to apply more than one tone within a group of buttons, apply different variants also to create appropriate hierarchy.
It’s recommended to lead with the primary button followed by secondary. On tablet and desktop, buttons should align to the left. On mobile, buttons should stack at full width with primary appearing first.
An exception to this guidance is when buttons appear in the context of a Stepper. In these scenarios, the primary button should align to the right. Read more about positioning Stepper buttons.
Tablet and desktop
Page content
Mobile
Page content
If you need to position buttons side by side on mobile instead, follow the Apps advice below.
Apps
It’s recommended to observe Apps best practice and position primary on the right, secondary on the left with buttons placed side by side, justified to the screen width.
The bleed prop allows the background colour to bleed out into the surrounding layout — leaving the button to only take up the space required for the label itself.
The bleed is only applied vertically, with exception to the transparent variant, which also applies horizontally to facilitate better alignment with surrounding text.
For example, we can align a button to a Heading element using an Inline, even though the button is actually taller than the heading. If we didn’t use the bleed prop in this case, the button would introduce unwanted space above and below the heading.
A button cannot be disabled (unless loading), as this is not an accessible solution and does not provide information to the user about how to fix the issue. Avoid disabled buttons where possible.When designing a form, instead of disabling the submit button when a required field is missing, allow the user to attempt to submit and fail. Then provide validation feedback informing the user of what they must do to progress.
Buttons let users take action or make a choice. A button is different from a link. Links take users somewhere.
Be clear and concise.
Be direct and use active language e.g. "Post ad".
Use 2 to 4 words only.
Use sentence case.
Don’t use punctuation, such as exclamation marks, full stops or commas.
One action only per button.
Don’t include pronouns in buttons.
Do
Don’t
Tell users what action they can take.
Buttons should always perform an action.
Use a verb and a noun e.g. Create [verb/action] job ad [noun/name].
It’s okay to drop the noun for common actions like, "Done", "Submit", "Next".
Do
Don’t
Let users know what happens next.
Be specific. People need to know what to expect when they click a button. Button content should make sense even if someone doesn’t read the content around it e.g. someone using a screenreader to jump through the links, someone scanning the page or someone with a small visual focus field.
Match the destination content. Button content should reflect the title of the destination content.
Never mislead people by mislabelling a button. We’ll lose their trust.
Braid components are very explicit about the properties they accept, which makes providing arbitrary data attributes not possible. Instead, a data prop can be provided as a single collection of data attributes.