Variants

<Button label="Get quotes" />

<Button label="Continue" variant="primary" />

<Button label="Save draft" variant="secondary" />

<Button label="Learn more" variant="tertiary" />

Inverse

Inside an inverse <Surface> this happens automatically — Surface is the source of truth. Pass inverse explicitly only for a dark or branded background that isn’t a Surface. Toggle to dark theme to see the canvas context.

<Surface tone="inverse" className="rounded-lg p-6">
<Button label="Get quotes" inverse />
</Surface>

<Surface tone="inverse" className="rounded-lg p-6">
<Button label="Continue" variant="primary" inverse />
</Surface>

<Surface tone="inverse" className="rounded-lg p-6">
<Button label="Save draft" variant="secondary" inverse />
</Surface>

<Surface tone="inverse" className="rounded-lg p-6">
<Button label="Learn more" variant="tertiary" inverse />
</Surface>

Sizes

<Button label="Get quotes" variant="primary" size="xxs" />

<Button label="Get quotes" variant="primary" size="xs" />

<Button label="Get quotes" variant="primary" size="sm" />

<Button label="Get quotes" variant="primary" />

<Button label="Get quotes" variant="primary" size="lg" />

<Button label="Get quotes" variant="primary" size="xl" />

States

<Button label="Continue" variant="primary" disabled />

<Button label="Submitting" variant="primary" loading />

Icons

Add an optional leadingIcon and/or trailingIcon to reinforce a button’s action. Icons are decorative — the label stays the accessible name — and they scale with the button size and inherit the label colour.

<Button label="Back" variant="primary" leadingIcon={MaterialArrowBack} />

<Button label="Next" variant="primary" trailingIcon={MaterialArrowForward} />

<Button label="Continue" variant="primary" leadingIcon={MaterialArrowBack} trailingIcon={MaterialArrowForward} />

Full width

<Button label="Get quotes" fullWidth />

Navigation

<Button label="View details" variant="primary" size="sm" href="/vacancies/1" />
<Button label="Apply now" variant="primary" size="sm" href="https://jobs.example.com" external />

When to use

Use a button to trigger an action or transition. Keep labels short and action-oriented — favour verbs like “Save”, “Submit”, or “Get quotes” over vague terms like “Click here”.

Variants

• Accent: the single most important action on a page — “Get quotes”, “Book now”. One accent button per viewport. Locked to lg/xl sizes.
• Primary: important actions that aren’t the page-level CTA — form submissions, confirmations. One primary per distinct area.
• Secondary: supporting actions paired alongside a primary — “Cancel”, “Save draft”. Has a visible border.
• Tertiary: low-emphasis actions — inline alternatives, toolbar items, supplementary links-as-buttons.

Sizes

Full width

Use fullWidth for mobile form submissions or stacked button groups where the button should span the container. Avoid it in desktop contexts where a natural content-width button is more appropriate.

Navigation vs action

Pass href when the control’s job is to go somewhere, and onClick/onPress when it performs an action. href renders a real anchor, which keeps prefetch, middle-click, ⌘-click, “open in new tab” and the no-JS fallback — all of which are lost if you fake navigation with onClick={() => window.location.assign(url)}. Add external for a destination outside the app, which opens a new tab and tells screen-reader users it will.

When not to use

• Text-styled links: use Link. Button is for button-styled controls; for navigation that should look like a link in a sentence or a standalone text link, Link is the right component.
• A navigating CTA that must be conditionally inert: the href branch forbids disabled/loading, because an <a> has no disabled attribute and the state could only ever be a visual lie. Use the action branch and navigate yourself.
• Destructive actions without confirmation: pair with a confirmation dialog.
• Multiple accent or primary buttons: if everything is high-emphasis, nothing is.

Props

Standard platform props also pass through to the rendered element (ButtonHTMLAttributes on web, PressableProps on native) — e.g. onMouseEnter/hitSlop, id/nativeID, aria-*. className/style stay blocked, along with the interaction/state props Button manages itself (type, aria-busy, onHoverIn/onFocus/etc).

Import

Web

import { Button } from '@checkatrade/components-web';

Native

import { Button } from '@checkatrade/components-native';

Basic usage

<Button label="Get quotes" />
<Button label="Continue" variant="primary" />
<Button label="Save draft" variant="secondary" />
<Button label="Cancel" variant="tertiary" />

Inverse on a dark background

<div
  style={{ background: 'var(--color-background-surface-brand-primary-default)', padding: '2rem' }}
>
  <Button label="Get quotes" inverse />
</div>

Full width

<Button label="Submit" variant="primary" fullWidth />

Loading state

<Button label="Submitting" variant="primary" loading />

Platform status

Accessibility

Web

• Uses a native <button> element — keyboard accessible by default. With href it renders a native <a> instead, so it is announced as a link and keeps the browser’s own navigation affordances.
• aria-label is set from the label prop, so the accessible name is always present even when the label is visually replaced by a spinner during loading.
• Loading state sets aria-busy="true".
• Focus ring is provided globally via @checkatrade/tokens/css/base — button:focus-visible gets a 3px solid outline with 2px offset. The inverse focus ring switches automatically via data-inverse on the underlying element.

React Native

• Uses Pressable with accessibilityRole="button" — announced as a button by screen readers on iOS (VoiceOver) and Android (TalkBack). With href the role becomes link, and react-native-web renders a real <a> (via href/hrefAttrs) so the web build gets genuine link semantics; on iOS/Android the press opens the URL through Linking.
• accessibilityLabel defaults to label, so the accessible name is always present. Override with the accessibilityLabel prop when the visible label needs context.
• Loading state sets accessibilityState={{ busy: true }}.
• Hover state (onHoverIn/onHoverOut) is active on react-native-web for web users; it is a no-op on iOS and Android.

Both platforms

• Every size renders at a fixed per-size height from @checkatrade/tokens (--sizing-button-height-{size} / sizingButtonHeight{Size}: 34/40/44/48/54/64 for xxs–xl) — a guaranteed consistent height across variants and states at a given size, not a free-form minimum. xxs/xs sit below the WCAG 2.5.5 (AAA) 44px touch target guidance by design; pick a size appropriate to the surrounding UI density.
• accent is locked to lg/xl to ensure the page-level CTA always has sufficient visual weight and touch target size.
• external appends “(opens in a new tab)” to the accessible name, so screen-reader users are warned before activating. There is deliberately no automatic open-in-new glyph (unlike Link) — Figma’s button spec has no slot for one; pass trailingIcon if the visual affordance is wanted.

Button Changelog

2026-05-08 — fullWidth and hover (PR #26)

Added

• fullWidth prop — stretches the button to fill its container width.

2026-05-07 — Code review (PR #18)

Changed

• Focus ring, cursor, and font-weight moved out of component classes into @checkatrade/tokens/css/base. The component no longer hardcodes these — they are provided by a single import at the app level.
• data-inverse attribute added to the underlying <button> element so base.css can target the inverse focus ring colour via button[data-inverse]:focus-visible.
• defaultVariants.size removed — it was dead code, always overridden by resolvedSize.
• Redundant onClick guard removed — <button disabled> natively prevents click events.

Added

• TypeScript discriminated union: variant="accent" now enforces size="xl" at compile time. Passing a smaller size to an accent button is a type error.
• Storybook: onPress action wired via argTypes instead of inline in each story arg. Accent story locks size control. AllVariants, AllVariantsInverse, and AllSizes stories added.

Fixed

• AllVariants story was mixing sizes; all variants now shown at xl for consistent comparison.

2026-04-23 — Initial implementation (PR #2, #15)

Added

• Button component with accent, primary, secondary, tertiary variants.
• sm, md, lg, xl sizes with token-backed padding and border radius.
• inverse, disabled, loading props.
• resolvedSize logic: accent defaults to xl, others to md.
• Full token coverage: colours, spacing, typography via Tailwind utilities.
• Storybook stories: Accent, Primary, Secondary, Tertiary, Disabled, Loading, AllVariants, AllVariantsInverse, AllSizes.
• Tests: rendering, interaction, disabled state, loading state (12 tests).

Button Changelog (Native)

2026-05-08 — fullWidth and hover (PR #26)

Added

• fullWidth prop — stretches the button to fill its container via style={{ width: '100%' }}.
• Hover state via onHoverIn/onHoverOut on Pressable — no-op on iOS/Android, active on react-native-web.

2026-05-07 — Alignment with web Button (PR #18)

Changed

• Variants renamed to match the web component: accent | primary | secondary | tertiary (previously primary | secondary | outline, where “primary” incorrectly used accent tokens and “outline” used tertiary tokens).
• Styling rewritten using Unistyles v3 StyleSheet.create(theme => ...) with variants and compoundVariants instead of StyleSheet.flatten with inline conditionals.
• effectiveVariant pattern removed — disabled state is now its own variant axis (isDisabled) rather than overriding the semantic variant.
• resolvedSize logic aligned with web: accent defaults to xl, others default to md.
• Spinner colour resolved directly from theme by props, not extracted from the resolved style object.

Added

• xl size with token-backed padding and border radius (spacingButtonXl*).
• inverse prop with compound variants covering all four variants and disabled state.
• TypeScript discriminated union: variant="accent" enforces size="xl" at compile time.
• Storybook: onPress action wired via argTypes. AllVariants, AllVariantsInverse, AllSizes stories added.
• Test: inverse prop rendering (2 tests). “Retains accessible name when loading” test added.

Fixed

• Font size and line height tokens were silently undefined — keys were typographyLabelFontSizeActionSm (non-existent). Corrected to typographyLabelFontSizeButtonSm/Md/Lg/Xl.
• Unistyles mock updated to strip variants/compoundVariants from style objects and expose a no-op useVariants so tests run without errors.

2026-04-23 — Initial implementation (PR #2, #3)

Added

• Button component with primary, secondary, outline variants (using accent, secondary, and tertiary tokens respectively).
• sm, md, lg sizes.
• disabled and loading props.
• accessibilityLabel override prop and testID support.
• registerTheme helper for Unistyles setup.
• Tests: rendering, interaction, disabled state, loading state (11 tests).