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="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 />

Full width

<Button label="Get quotes" fullWidth />

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 xl size.
• 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.

When not to use

• Navigation: use a link (<a> on web, or your app’s navigation primitive on native) instead. Buttons are for actions, not destinations.
• Destructive actions without confirmation: pair with a confirmation dialog.
• Multiple accent or primary buttons: if everything is high-emphasis, nothing is.

Props

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.
• 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).
• 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

• Minimum height is 44px, meeting WCAG 2.5.5 (AAA) touch target guidance.
• accent is locked to xl to ensure the page-level CTA always has sufficient visual weight and touch target size.

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).