Design System Beacon

Button Icon

Icon-only buttons for compact actions. Use button icons for space-efficient controls, toolbars, and secondary actions.

Overview

Button Icon is a specialized button component that displays only an icon, without text. It shares all the same properties as the Button component but is optimized for icon-only use cases. Button icons are square-shaped and maintain consistent sizing across all variants.

All button icon styles are built using design tokens, ensuring consistency across themes and hues. Use the interactive playground below to explore all available combinations.

Interactive Playground

Use the controls to customize the button icon and see how it looks in real-time. Toggle between themes and hues to see how button icons adapt to different contexts.

Variant

State

Color

Size

Radius

<ButtonIcon
  icon={<SearchIcon />}
/>

Anatomy

A button icon consists of several parts that work together to create a cohesive interactive element.

Containersquare, padding, border-radius

Iconcentered, size-based scaling

Border--border-width-25

Variants & States

Button icons come in four main variants, each suited for different levels of emphasis and use cases.

Filled

Primary actions and high-emphasis buttons. Use for the main action in a toolbar or compact interface.

Tonal

Secondary actions with subtle emphasis. Use for supporting actions that don't need primary attention.

Outline

Tertiary actions with border emphasis. Use for less important actions or when you need visual separation.

Link

Text-only buttons for low-emphasis actions. Use for navigation or actions that don't need visual weight.

For a complete matrix of all button icon variants, sizes, and states, see the Button Icon component in Figma.

Usage Guidelines

Use button icons for space-efficient controls in toolbars and compact interfaces.
Use filled button icons for primary actions in icon-only contexts.
Provide clear, recognizable icons that communicate the action.
Use appropriate sizes based on context and importance.
Ensure button icons meet WCAG contrast requirements.
Always provide aria-label for accessibility when the icon alone isn't clear.

Don't

Don't use button icons when text labels would be clearer.
Don't use ambiguous or unclear icons.
Don't use button icons for navigation (use links instead).
Don't make button icons too small to tap comfortably on mobile.
Don't use button icons for decorative purposes.
Don't forget to provide accessible labels for screen readers.

Accessibility

Button icons must be keyboard accessible. Use type="button" for non-submit buttons.
Always provide descriptive labels for screen readers using aria-label.
Ensure focus states are clearly visible with sufficient contrast.
Use disabled attribute for disabled buttons, not just visual styling.
Loading states should be announced to screen readers.

API Reference

ButtonIcon component props and types.

ButtonIconProps

interface ButtonIconProps {
  variant?: "filled" | "tonal" | "outline" | "link";
  size?: "xs" | "sm" | "md" | "lg" | "xl";
  cornerRadius?: 0 | 1 | 2 | 3 | 4 | 5;
  icon?: React.ReactNode;
  disabled?: boolean;
  loading?: boolean;
  onClick?: () => void;
  type?: "button" | "submit" | "reset";
  "aria-label"?: string;
}

Props

variant

"filled" | "tonal" | "outline" | "link"

"filled"

Button style variant

size

"xs" | "sm" | "md" | "lg" | "xl"

"md"

Button size

cornerRadius

0 | 1 | 2 | 3 | 4 | 5

2

Corner radius step: 0=None, 1=100 (4px), 2=200 (8px), 3=300 (12px), 4=400 (16px), 5=Full (100%)

icon

React.ReactNode

—

Icon to display in the button

disabled

boolean

false

Disable button interaction

loading

boolean

false

Show loading state

Usage Examples

Copyable code snippets for common button icon use cases.

Basic Button Icon

import { ButtonIcon } from 'beacon-ui';
import { SearchIcon } from 'beacon-icons';

<ButtonIcon icon={<SearchIcon size="sm" />} />

All Variants

import { ButtonIcon } from 'beacon-ui';
import { SearchIcon } from 'beacon-icons';

<ButtonIcon variant="filled" icon={<SearchIcon size="sm" />} />
<ButtonIcon variant="tonal" icon={<SearchIcon size="sm" />} />
<ButtonIcon variant="outline" icon={<SearchIcon size="sm" />} />
<ButtonIcon variant="link" icon={<SearchIcon size="sm" />} />

Sizes

import { ButtonIcon } from 'beacon-ui';
import { SearchIcon } from 'beacon-icons';

<ButtonIcon size="xs" icon={<SearchIcon size="xs" />} />
<ButtonIcon size="sm" icon={<SearchIcon size="xs" />} />
<ButtonIcon size="md" icon={<SearchIcon size="sm" />} />
<ButtonIcon size="lg" icon={<SearchIcon size="rg" />} />
<ButtonIcon size="xl" icon={<SearchIcon size="rm" />} />

Disabled State

import { ButtonIcon } from 'beacon-ui';
import { SearchIcon } from 'beacon-icons';

<ButtonIcon disabled icon={<SearchIcon size="sm" />} />