IconButton — Design System

Examples

Accessible name

An icon-only action always exposes a concise aria-label.

IconButton with an accessible name

import { Bell } from "@phuctech/ui/icons";
import { IconButton } from "@phuctech/ui/components/icon-button";

export function Example() {
  return (
    <IconButton aria-label="View notifications" variant="outline">
      <Bell aria-hidden="true" />
    </IconButton>
  );
}

Variant and size

Match toolbar emphasis and touch target size to the surrounding context.

IconButton variant and size comparison

import { Bell } from "@phuctech/ui/icons";
import { IconButton } from "@phuctech/ui/components/icon-button";

export function Example() {
  return (
    <IconButton aria-label="View notifications" variant="outline">
      <Bell aria-hidden="true" />
    </IconButton>
  );
}

Disabled and loading

Inherited Button states keep the target stable and prevent repeat activation.

Disabled and loading IconButton states

import { Bell } from "@phuctech/ui/icons";
import { IconButton } from "@phuctech/ui/components/icon-button";

export function Example() {
  return (
    <IconButton aria-label="View notifications" variant="outline">
      <Bell aria-hidden="true" />
    </IconButton>
  );
}

Tooltip adds context but does not replace the accessible name.

import { Bell } from "@phuctech/ui/icons";
import { IconButton } from "@phuctech/ui/components/icon-button";

export function Example() {
  return (
    <IconButton aria-label="View notifications" variant="outline">
      <Bell aria-hidden="true" />
    </IconButton>
  );
}

When to use

Use IconButton when the action is familiar from its icon and the surrounding context makes it easy to understand. Use a text Button when the action is new, high impact, or needs a longer explanation.

Good fit

Notifications, search, close, or compact toolbar actions with a stable label.

Use text instead

Do not hide “Delete account” or another consequential action behind an unfamiliar icon.

Usage

import { Bell } from "@phuctech/ui/icons";
import { IconButton } from "@phuctech/ui/components/icon-button";

export function Example() {
  return (
    <IconButton aria-label="View notifications" variant="outline">
      <Bell aria-hidden="true" />
    </IconButton>
  );
}

The required aria-label is the accessible name. Keep it short and describe the action, not the icon.

Variants and states

IconButton sizes and states
Option	Use for
`xs`, `sm`	Dense toolbars and compact rows.
`md`	The normal action target in a toolbar.
`lg`	A more prominent action or touch-first surface.
`disabled`, `loading`	Inherited Button states; loading keeps the target size stable.

Icons

Use a PhucTech icon from @phuctech/ui/icons and mark it aria-hidden="true". Do not use the icon as the only accessible name; the explicit aria-label is the contract.

API

Component API
Prop	Type	Default	Description	Constraints
`aria-label`	`string`	`required`	Accessible name for the icon-only action.	Required; describe the action in plain language.
`size`	`"xs" \| "sm" \| "md" \| "lg"`	`"md"`	Maps to Button icon sizing and the shared touch-target scale.	Choose a size that matches the surrounding density.
`variant`	`Button variant`	`"default"`	Inherited visual intent from Button.	Use a lower-emphasis variant for toolbars when appropriate.
`loading`	`boolean`	`false`	Inherited in-flight state from Button.	Use while the action is being processed.
`disabled`	`boolean`	`false`	Prevents activation.	Explain an unexpected unavailable state nearby.

Tokens

Component tokens
Token	Role	Effective value	Usage
`--size-control-*`	Touch target	`xs / sm / md / lg`	IconButton maps each public size to the Button control scale.
`--size-icon-*`	Icon geometry	`xs / sm / md / lg`	PhucTech icons inherit the matching Button icon size.
`--focus-ring-*`	Keyboard focus	`3px / 2px / semantic focus`	Uses the shared visible focus contract.

Accessibility

Provide the required aria-label; a tooltip is not a replacement for the accessible name.
Test focus, Enter, Space, disabled, and loading states with a keyboard.
Keep the target at least the shared control size; do not shrink an icon only to fit more actions.

Do and don’t

Use one clear action label, a familiar icon, and a visible focus ring.

Don’t

Render an unlabeled icon, rely on color alone, or put many ambiguous icons side by side.

Button provides the base variants, loading behavior, and focus contract.
Icons documents PhucTech sizing and decorative semantics.