Icon Button

A square button that displays only an icon, with no visible text label. Use for compact toolbars, action menus, and inline controls where the icon meaning is universally understood.

Preview

Sizes

States

Variants

• Primary -- solid brand fill. Use for the single most important icon action.
• Secondary -- transparent with border. Use for supporting icon actions.
• Ghost -- no fill or border. Use in toolbars or dense layouts.
• Danger -- solid red fill. Use for destructive actions like delete.

Sizes

Size	Dimensions	Icon size
sm	32 × 32 px	16 × 16 px
md	40 × 40 px	20 × 20 px
lg	48 × 48 px	24 × 24 px

States

State	Appearance
Default	Resting state
Hover	Background shift matching the text button variant
Focus	2 px brand-purple ring with 2 px offset
Active	Darker background than hover
Disabled	50 % opacity, cursor: not-allowed

Props

Prop	Type	Default	Description
variant	'primary' | 'secondary' | 'ghost' | 'danger'	'ghost'	Visual style
size	'sm' | 'md' | 'lg'	'md'	Button dimensions
disabled	boolean	false	Disables interaction
aria-label	string	required	Accessible name (no visible text)
icon	ReactNode	--	Icon element to render
className	string	--	Additional CSS classes

Code example

React

import { IconButton } from '@thepace/lexicon/components';
import { PlusIcon, TrashIcon } from '@thepace/lexicon/icons';

<IconButton variant="ghost" aria-label="Add item" icon={<PlusIcon />} />
<IconButton variant="danger" aria-label="Delete" icon={<TrashIcon />} />

Vanilla HTML

<button class="lex-icon-button lex-icon-button--ghost lex-icon-button--md"
        aria-label="Add item">
  <svg width="20" height="20" viewBox="0 0 20 20" fill="none"
       stroke="currentColor" stroke-width="2" stroke-linecap="round">
    <line x1="10" y1="4" x2="10" y2="16"/>
    <line x1="4" y1="10" x2="16" y2="10"/>
  </svg>
</button>

CSS class reference

Class	Purpose
.lex-icon-button	Base styles
.lex-icon-button--primary	Primary variant
.lex-icon-button--secondary	Secondary variant
.lex-icon-button--ghost	Ghost variant
.lex-icon-button--danger	Danger variant
.lex-icon-button--sm	Small size (32 px)
.lex-icon-button--md	Medium size (40 px)
.lex-icon-button--lg	Large size (48 px)

Accessibility

• aria-label is required since there is no visible text label.
• Focus ring matches the standard Button focus style.
• Keyboard: Enter and Space trigger the action.
• If the icon conveys meaning beyond the label, mark the <svg> with role="img" and a <title>.

Guidelines

Do

• Always provide a descriptive aria-label (e.g. "Close dialog", not "X").
• Use ghost variant in toolbars to keep visual density low.
• Pair with a Tooltip for discoverability when the icon meaning may not be obvious.

Don't

• Don't omit aria-label — the button will be invisible to screen readers.
• Don't use icon buttons for primary page actions where a text label would be clearer.