IconButton | omverse-ui

Overview

Icon-only button with tooltip, badge, toggle and FAB support. 6 variants, 5 sizes.

Icon button variants

Live preview

Every icon-only action needs a concise accessible name.

IconButtonExample.tsx

tsx

1import { IconButton } from 'omverse-ui'
2 
3// 6 variants
4<IconButton icon="heart" variant="filled"      aria-label="Like" />
5<IconButton icon="heart" variant="outlined"    aria-label="Like" />
6<IconButton icon="heart" variant="tonal"       aria-label="Like" />
7<IconButton icon="heart" variant="ghost"       aria-label="Like" />
8<IconButton icon="heart" variant="standard"    aria-label="Like" />
9<IconButton icon="heart" variant="destructive" aria-label="Like" />
10 
11// gradient is a boolean prop (not a variant) — combine with filled:
12<IconButton icon="heart" variant="filled" gradient aria-label="Like" />

Use icon buttons only for actions with widely understood symbols and provide an aria-label that describes the action.

Anatomy

Root container and spacing boundary.
Primary content and optional secondary metadata.
State indicators and utility affordances (icons, badges, controls).
Optional helper text, grouping, and behavioral wrappers.

When to use

Choose IconButton when a repeated, structured interaction is required.
Use it for clear, consistent operations across similar surfaces.
Use in forms, lists, and action workflows where clarity matters.

When not to use

Do not use only for decorative layout without interaction meaning.
Avoid duplicating the same behavior without distinct user context.
Prefer simpler HTML or textual content for static, non-interactive labels.

Variants

Component variants should be documented by API props and examples below.

States

Common states include idle, active, disabled, focused, and loading/pending states where applicable.

Behavior

Behavior should remain deterministic and keyboard-friendly, with clear visual feedback for every state transition.

Accessibility

Use semantic structure and visible labels whenever possible.
Preserve keyboard navigation and focus visibility.
Announce status and changes when context requires it.

Content guidelines

Prefer short, clear labels.
Keep content actions scannable and outcome-oriented.
Use consistent wording across similar components.

Examples

Variants

Live preview

6 emphasis levels — filled · outlined · tonal · ghost · standard · destructive. gradient is a boolean prop applied on top of a variant.

variant="filled" gradient

App.tsx

tsx

1import { IconButton } from 'omverse-ui'
2 
3// 6 variants
4<IconButton icon="heart" variant="filled"      aria-label="Like" />
5<IconButton icon="heart" variant="outlined"    aria-label="Like" />
6<IconButton icon="heart" variant="tonal"       aria-label="Like" />
7<IconButton icon="heart" variant="ghost"       aria-label="Like" />
8<IconButton icon="heart" variant="standard"    aria-label="Like" />
9<IconButton icon="heart" variant="destructive" aria-label="Like" />
10 
11// gradient is a boolean prop (not a variant) — combine with filled:
12<IconButton icon="heart" variant="filled" gradient aria-label="Like" />

Sizes

Live preview

xs · sm · md · lg · xl — all sizes keep a 44 × 44 px minimum touch target

App.tsx

tsx

1<IconButton icon="settings" size="xs" aria-label="Settings" />
2<IconButton icon="settings" size="sm" aria-label="Settings" />
3<IconButton icon="settings" size="md" aria-label="Settings" />
4<IconButton icon="settings" size="lg" aria-label="Settings" />
5<IconButton icon="settings" size="xl" aria-label="Settings" />

Shape

Live preview

circle (default) or square — square pairs well with FAB

App.tsx

tsx

1// circle (default)
2<IconButton icon="plus" variant="filled" shape="circle" aria-label="Add" />
3 
4// square
5<IconButton icon="plus" variant="filled" shape="square" aria-label="Add" />

Toggle

Live preview

toggle enables a pressed / unpressed state with aria-pressed — click to switch

App.tsx

tsx

1// Uncontrolled toggle — component manages its own state
2<IconButton icon="heart"     variant="ghost" toggle aria-label="Like" />
3<IconButton icon="bookmark"  variant="ghost" toggle aria-label="Bookmark" />
4<IconButton icon="star"      variant="ghost" toggle aria-label="Star" />
5 
6// Controlled toggle with pressedIcon
7<IconButton
8  icon="bookmark"
9  pressedIcon="bookmark"
10  variant="ghost"
11  toggle
12  pressed={saved}
13  onPressedChange={setSaved}
14  aria-label="Save"
15/>

With badge

Live preview

badge={true} shows a red dot · badge={n} shows a count (capped at 99+)

App.tsx

tsx

1// Dot badge (true)
2<IconButton icon="bell" variant="outlined" badge={true} aria-label="Notifications" />
3 
4// Count badge
5<IconButton icon="bell"     variant="outlined" badge={3}  aria-label="3 notifications" />
6<IconButton icon="mail"     variant="outlined" badge={12} aria-label="12 messages" />
7<IconButton icon="bookmark" variant="outlined" badge={99} aria-label="99 saved items" />

Live preview

loading replaces the icon with a spinner and disables interaction

App.tsx

tsx

1// loading shows a spinner and disables interaction
2<IconButton icon="refresh" variant="filled"   loading aria-label="Refresh" />
3<IconButton icon="upload"  variant="outlined" loading aria-label="Upload" />

FAB (Floating Action Button)

Live preview

fab adds an elevation shadow — pair with size='xl' and shape='square' for the classic Material FAB

App.tsx

tsx

1// fab adds an elevation shadow — pair with size="xl" for classic FAB
2<IconButton icon="plus" variant="filled" fab         aria-label="Add" />
3<IconButton icon="edit" variant="tonal"  fab         aria-label="Edit" />
4<IconButton icon="plus" variant="filled" fab size="xl" shape="square" aria-label="Add" />

Gradient

Live preview

gradient is a boolean prop — applies a brand gradient on filled and destructive variants

App.tsx

tsx

1// gradient applies a brand gradient background (filled / destructive)
2<IconButton icon="plus"  variant="filled"      gradient aria-label="Add" />
3<IconButton icon="trash" variant="destructive" gradient aria-label="Delete" />

Disabled

Live preview

disabled reduces opacity and prevents all interaction

App.tsx

tsx

1<IconButton icon="settings" variant="filled"   disabled aria-label="Settings" />
2<IconButton icon="settings" variant="outlined" disabled aria-label="Settings" />
3<IconButton icon="settings" variant="ghost"    disabled aria-label="Settings" />

Props / API

Api Props

Props

PropTypeDefaultDescription

iconIconName—Icon to display — required

aria-labelstring—Accessible label — TypeScript-required for icon-only buttons

size'xs' | 'sm' | 'md' | 'lg' | 'xl''md'Button size (all sizes keep a 44 × 44 px minimum touch target)

shape'circle' | 'square''circle'Button shape

togglebooleanfalseToggleable on / off state with aria-pressed

pressedbooleanundefinedControlled pressed state for toggle mode

onPressedChange(pressed: boolean) => voidundefinedCallback fired when pressed state changes

pressedIconIconNameundefinedIcon shown when toggle is in pressed state

badgeboolean | numberundefinedtrue → red dot · number → count badge (capped at 99+)

tooltipbooleantrueShow a tooltip with the aria-label text on hover / focus

loadingbooleanfalseShows a loading spinner and disables interaction

gradientbooleanfalseApply brand gradient background (filled / destructive variants)

fabbooleanfalseFloating action button style — adds elevation shadow

disabledbooleanfalseDisables the button