Icon Button

Variants

<IconButton icon={MaterialSearch} aria-label="Search" variant="accent" />

<IconButton icon={MaterialSearch} aria-label="Search" variant="primary" />

<IconButton icon={MaterialFavorite} aria-label="Add to favourites" variant="secondary" />

<IconButton icon={MaterialSettings} aria-label="Settings" 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">
<IconButton icon={MaterialSearch} aria-label="Search" variant="accent" inverse />
</Surface>

<Surface tone="inverse" className="rounded-lg p-6 flex gap-4">
<IconButton icon={MaterialHome} aria-label="Home" variant="primary" />
<IconButton icon={MaterialFavorite} aria-label="Favourites" variant="secondary" />
<IconButton icon={MaterialSettings} aria-label="Settings" variant="tertiary" />
</Surface>

Sizes

The shell is always square. accent only accepts lg and xl, so the size ramp below uses primary.

<IconButton icon={MaterialSearch} aria-label="Search" variant="primary" size="sm" />

<IconButton icon={MaterialSearch} aria-label="Search" variant="primary" size="md" />

<IconButton icon={MaterialSearch} aria-label="Search" variant="primary" size="lg" />

<IconButton icon={MaterialSearch} aria-label="Search" variant="primary" size="xl" />

States

<IconButton icon={MaterialSearch} aria-label="Search" variant="primary" disabled />

<IconButton icon={MaterialSearch} aria-label="Searching…" variant="primary" loading />

When to use

Use an icon button for a compact action where a recognisable glyph communicates the intent on its own — search, favourite, settings, close. Because there is no visible text, the glyph must be unambiguous and you must always provide an accessible label for assistive technology.

Prefer a text Button when the action’s meaning isn’t obvious from an icon alone, or when you have room for a label. Icon buttons trade clarity for compactness, so reserve them for well-understood, conventional actions.

Variants

• Accent: the single most important icon action on a page. One accent button per viewport. Restricted to lg and xl sizes.
• Primary: important icon actions that aren’t the page-level CTA. One primary per distinct area.
• Secondary: supporting actions paired alongside a primary. Has a visible border.
• Tertiary: low-emphasis icon actions — toolbar toggles, supplementary controls. Transparent background.

Sizes

The shell is square at every size. accent is locked to lg and xl.

Default size is xl for accent and md for all other variants.

When not to use

• Actions whose meaning isn’t obvious: use a text Button with a clear label instead.
• Navigation: use a link (<a> on web, or your app’s navigation primitive on native). Buttons are for actions, not destinations.
• Multiple accent or primary icon 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 IconButton manages itself (type, aria-busy, onHoverIn/onFocus/etc).

Import

Web

import { IconButton } from '@checkatrade/components-web';
import { MaterialHome } from '@checkatrade/icons/react';

Native

import { IconButton } from '@checkatrade/components-native';
import Home from '@checkatrade/icons/rn/home';

Basic usage

<IconButton icon={MaterialHome} aria-label="Home" variant="accent" />
<IconButton icon={MaterialSearch} aria-label="Search" variant="primary" />
<IconButton icon={MaterialFavorite} aria-label="Add to favourites" variant="secondary" />
<IconButton icon={MaterialSettings} aria-label="Settings" variant="tertiary" />

Inverse on a dark background

<div
  style={{ background: 'var(--color-background-surface-brand-primary-default)', padding: '2rem' }}
>
  <IconButton icon={MaterialHome} aria-label="Home" variant="accent" inverse />
</div>

Loading state

<IconButton icon={MaterialSearch} aria-label="Searching…" variant="primary" loading />

Platform status

Accessibility

Web

• Uses a native <button> element — keyboard accessible by default.
• aria-label is required: there is no visible text, so the accessible name must always be provided.
• The glyph is rendered with aria-hidden="true" so it isn’t announced a second time — the label alone carries the meaning.
• Loading state sets aria-busy="true", and the aria-label is retained as the accessible name while the spinner is shown.
• 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 is required: it provides the accessible name announced by screen readers.
• The glyph is wrapped with accessibilityElementsHidden and importantForAccessibility="no-hide-descendants" so it isn’t announced separately from the label.
• Loading state sets accessibilityState={{ busy: true }}.

Both platforms

• Minimum dimensions are 40 × 40px (sm), meeting WCAG 2.5.5 (AAA) touch target guidance at every size.
• accent is locked to lg | xl to ensure the page-level CTA always has sufficient visual weight and touch target size.

No releases yet.