Icon Button Component

The IconButton component is a compact, icon-only button built for toolbars, tables, cards, and dashboard actions. It shares the same variant system as Button for visual consistency, while sizing the icon and touch target together so the icon never looks lost inside the button.

Always pass an aria-label since there is no visible text — it's the only way assistive tech can describe the action. Use size to scale the button and icon together, and variant to match the surrounding UI.

Import Component From Library

javascript

1import { IconButton } from "@neuctra/ui";

Basic Usage Code

Pass any icon as the icon prop and always provide an aria-label describing the action.

1import { IconButton } from '@neuctra/ui';
2import { Heart } from 'lucide-react';
3
4function BasicExample() {
5  return (
6    <IconButton
7      icon={<Heart />}
8      aria-label="Like"
9      onClick={() => console.log('Liked')}
10    />
11  );
12}

Basic Example

Variants

Ten variants cover brand, neutral, and semantic (status) actions — the same set used by Button.

Sizes

Five sizes scale both the button footprint and the icon together — no need to size the icon separately.

Disabled State

Props Table

All available props for the IconButton component.

Prop	Type	Default	Description
icon	React.ReactNode	—	The icon displayed inside the button. Required.
variant	"default" \| "soft" \| "outline" \| "ghost" \| "secondary" \| "destructive" \| "success" \| "warning" \| "info" \| "link"	"default"	Controls the visual style of the button.
size	"xs" \| "sm" \| "md" \| "lg" \| "xl"	"sm"	Controls the button footprint and the icon size together.
aria-label	string	—	Accessible label describing the action. Required since the button has no visible text.
disabled	boolean	false	Disables the button.
className	string	—	Root button classes.
iconClassName	string	—	Classes for the icon wrapper.
iconStyle	React.CSSProperties	—	Inline styles for the icon wrapper.
...rest	React.ButtonHTMLAttributes<HTMLButtonElement>	—	Native button props like onClick, type, disabled.

Common Mistakes

<IconButton icon={<Heart />} />

Missing aria-label — screen readers can't describe an icon-only button without it.

<IconButton icon={<Heart />}>Like</IconButton>

IconButton doesn't render children — use aria-label for the accessible name, and Button if you need visible text.

<IconButton size="20px" icon={<Heart />} aria-label="Like" />

Only predefined sizes are allowed: xs, sm, md, lg, xl

<IconButton icon={<Heart />} aria-label="Like" />

Always pair the icon with a descriptive aria-label.

Pro Tips

Always set aria-label — it's the only accessible name an icon-only button has.
Pass icons unsized (e.g. <Heart />) and let size control the icon dimensions consistently.
Use ghost or soft variants for toolbar and table row actions, and destructive for delete/remove actions.
Match size with nearby inputs or buttons to keep the row's touch targets visually aligned.
Use iconClassName / iconStyle only for fine-tuning icon rendering — prefer className for layout and spacing.

Frequently Asked Questions

How do I install and import the IconButton component?

Install the @neuctra/ui package, then import it with: import { IconButton } from "@neuctra/ui";

What variants and sizes does IconButton support?

IconButton supports variants: default, soft, outline, ghost, secondary, destructive, success, warning, info, link and sizes: xs, sm, md, lg, xl. Use the variant and size props to switch between them, or pass a className to layer on custom Tailwind CSS classes.

Is the IconButton component accessible?

IconButton is built with semantic HTML and standard ARIA attributes, and supports keyboard navigation and focus states out of the box, so it works well with screen readers and keyboard-only users.