# IconButton
## Summary
`IconButton` is the icon-only action variant built on the same button foundation as `Button`. It is the compact action layer when visible text would add noise rather than clarity.
## Imports
```tsx
import {
IconButton,
type IconButtonProps,
type IconButtonSize,
} from '@vega-ui/react';
```
## Exported Types
- `IconButtonProps`
- `IconButtonSize`
## Basic Usage
```tsx
import { Icon, IconButton, Text } from '@vega-ui/react';
import { EllipsisIcon, PencilIcon, Share2Icon } from '@vega-ui/icons';
import { useState } from 'react';
export default function BasicUsage() {
const [lastAction, setLastAction] = useState('');
return (
);
}
```
## Variants
- Sizes: `xs`, `sm`, `md`, `lg`, `xl`
- Variants and appearances inherited from the button foundation
- Composition: default button or `asChild`
## Edge Cases
- Always provide an `aria-label` because visible text is usually absent.
- Keep icon glyph size visually balanced with the button size token.
- Use regular `Button` when visible text would improve clarity.
- If the icon meaning depends on surrounding context too heavily, a text button is usually the safer choice.
## Common Mistakes
- Omitting `aria-label`.
- Putting long text inside `IconButton`.
- Using icon-only actions where the meaning is not already recognizable.
## Examples
### Basic
#### Basic: header actions with explicit names
Every icon-only action needs its own `aria-label`: the component never adds one. Inside `IconButton` an `Icon` without `size` scales with the button through `--icon-size`.
```tsx
import { Icon, IconButton, Text } from '@vega-ui/react';
import { EllipsisIcon, PencilIcon, Share2Icon } from '@vega-ui/icons';
import { useState } from 'react';
export default function BasicUsage() {
const [lastAction, setLastAction] = useState('');
return (
);
}
```
#### Basic: sizes
`size` sets the square side from `xs` to `xl`; the nested icon follows at one third of the button size.
```tsx
import { Icon, IconButton, type IconButtonSize } from '@vega-ui/react';
import { SettingsIcon } from '@vega-ui/icons';
const sizes: IconButtonSize[] = ['xs', 'sm', 'md', 'lg', 'xl'];
export default function Sizes() {
return (
{sizes.map((size) => (
))}
);
}
```
### Controlled/Stateful
#### Controlled/Stateful: favorite toggle with aria-pressed
The label stays "Favorite" and the state lives in `aria-pressed`, so a screen reader announces "Favorite, toggle button, pressed". Changing the label on every click would hide the state instead.
```tsx
import { Icon, IconButton } from '@vega-ui/react';
import { HeartIcon } from '@vega-ui/icons';
import { useState } from 'react';
export default function ParentOwnedFavoriteToggle() {
const [favorite, setFavorite] = useState(false);
const count = favorite ? 129 : 128;
return (
setFavorite(!favorite)}
>
{count} people saved this recipe
);
}
```
#### Controlled/Stateful: copy with temporary feedback
The icon swaps to a check for two seconds after copying, and a status region announces "Copied", because an icon change alone is silent for screen readers.
```tsx
import { Icon, IconButton, VisuallyHidden } from '@vega-ui/react';
import { CheckIcon, CopyIcon } from '@vega-ui/icons';
import { useEffect, useState } from 'react';
const inviteLink = 'https://app.example.com/invite/7Fq2-K9xD';
export default function CopyToClipboard() {
const [copied, setCopied] = useState(false);
useEffect(() => {
if (!copied) return;
const timer = setTimeout(() => setCopied(false), 2000);
return () => clearTimeout(timer);
}, [copied]);
const copy = async () => {
await navigator.clipboard.writeText(inviteLink);
setCopied(true);
};
return (