XDS — Design System

XDSIconButton@xds/core · IconButton

Usage

A button that shows only an icon with no visible text. Use IconButton in toolbars, table rows, and compact UI where space is tight and the icon is universally understood.

Best practices

Guidance	Practices
Do	Make the aria-label specific — a trash icon labeled "Delete conversation" is clearer than just "Delete" for screen readers.
Do	Add a tooltip — even a gear icon can mean Settings, Preferences, or Configure.
Do	Use ghost in toolbars and dense areas to reduce visual clutter.
Don't	Use IconButton if the action isn't obvious from the icon alone — use Button with text.
Don't	Skip the tooltip — label only reaches screen readers, sighted users need the hover hint.

Import

ts
import {XDSIconButton} from '@xds/core/IconButton'

Props

Prop	Type	Description
labelrequired	string	Accessible label. Used as aria-label (not rendered as visible text).
iconrequired	ReactNode	Icon element rendered inside the button.
variant	'primary' \| 'secondary' \| 'ghost' \| 'destructive' (default: 'secondary')	Visual style variant.
size	'sm' \| 'md' \| 'lg' (default: 'md')	Size variant.
isLoading	boolean (default: false)	Shows a loading spinner and disables interaction.
isDisabled	boolean (default: false)	Disables the button.
tooltip	string	Tooltip text shown on hover.
onClick	(e: MouseEvent) => void	Standard click handler.
clickAction	(e: MouseEvent) => void \| Promise<void>	Async click handler with automatic loading state.

Examples

Common configurations, variations, and states.

IconButton — Action BarRow of ghost icon buttons for a compact action toolbar

tsx
'use client';
import {XDSIconButton} from '@xds/core/IconButton';
import {XDSIcon} from '@xds/core/Icon';
import {XDSHStack} from '@xds/core/Stack';
export default function IconButtactionBar() {
  return (
    <XDSHStack gap={1}>
      <XDSIconButton
        label="Search"
        icon={<XDSIcon icon="search" color="inherit" />}
        variant="ghost"
      />
      <XDSIconButton
        label="Copy"
        icon={<XDSIcon icon="copy" color="inherit" />}
        variant="ghost"
      />
      <XDSIconButton
        label="Info"
        icon={<XDSIcon icon="info" color="inherit" />}
        variant="ghost"
      />
      <XDSIconButton
        label="Menu"
        icon={<XDSIcon icon="menu" color="inherit" />}
        variant="ghost"
      />
      <XDSIconButton
        label="Close"
        icon={<XDSIcon icon="close" color="inherit" />}
        variant="ghost"
      />
    </XDSHStack>
  );
}

IconButton — Loading StateIcon buttons that show a loading spinner on click for async feedback

tsx
'use client';
import {useState} from 'react';
import {XDSIconButton} from '@xds/core/IconButton';
import {XDSIcon} from '@xds/core/Icon';
import {XDSHStack} from '@xds/core/Stack';
export default function IconButtonLoadingToggle() {
  const [loadingId, setLoadingId] = useState<string | null>(null);
  function handleClick(id: string) {
    setLoadingId(id);
    setTimeout(() => setLoadingId(null), 1500);
  }
  return (
    <XDSHStack gap={2}>
      <XDSIconButton
        label="Copy"
        icon={<XDSIcon icon="copy" color="inherit" />}
        variant="primary"
        isLoading={loadingId === 'copy'}
        onClick={() => handleClick('copy')}
      />
      <XDSIconButton
        label="Search"
        icon={<XDSIcon icon="search" color="inherit" />}
        isLoading={loadingId === 'search'}
        onClick={() => handleClick('search')}
      />
      <XDSIconButton
        label="Close"
        icon={<XDSIcon icon="close" color="inherit" />}
        variant="ghost"
        isLoading={loadingId === 'close'}
        onClick={() => handleClick('close')}
      />
    </XDSHStack>
  );
}

IconButton — With TooltipsIcon buttons with tooltips that explain each action on hover

tsx
'use client';
import {XDSIconButton} from '@xds/core/IconButton';
import {XDSIcon} from '@xds/core/Icon';
import {XDSHStack} from '@xds/core/Stack';
export default function IconButtonTooltipIconButton() {
  return (
    <XDSHStack gap={2}>
      <XDSIconButton
        label="Search"
        icon={<XDSIcon icon="search" color="inherit" />}
        variant="ghost"
        tooltip="Search items"
      />
      <XDSIconButton
        label="Copy link"
        icon={<XDSIcon icon="copy" color="inherit" />}
        variant="ghost"
        tooltip="Copy to clipboard"
      />
      <XDSIconButton
        label="More options"
        icon={<XDSIcon icon="moreHorizontal" color="inherit" />}
        variant="ghost"
        tooltip="More options"
      />
    </XDSHStack>
  );
}

Showcase source

tsx
'use client';
import {XDSIconButton} from '@xds/core/IconButton';
import {XDSIcon} from '@xds/core/Icon';
export default function IconButtonShowcase() {
  return (
    <XDSIconButton
      label="Settings"
      icon={<XDSIcon icon="wrench" color="inherit" />}
    />
  );
}