---
name: action-icon-usage
description: >
Use when an app needs the @techsio/ui-kit ActionIcon atom — an icon-only,
square action button (toolbar/inline actions). Covers tone, size, disabled
state, accessible labelling, and token-first styling.
metadata:
type: "core"
library: "@techsio/ui-kit"
component: "ActionIcon"
component_version: "2.0.0"
requires: "ux-guidelines"
resources: "references/ux.md ../../references/component-contracts.md ../../references/consumer_app_usage_rules.md"
audience: "consumer"
---
> Portable scope: Use the installed package's exported types and bundled sibling skills. Repository source paths are optional contributor evidence, not consumer prerequisites; use the consuming app's own checks. Resolve ../../references/ paths from this skill's folder, not the app working directory.
# ActionIcon usage
`ActionIcon` is an icon-only, square action button for compact/inline actions where a
full `Button` with a text label would be too heavy (toolbars, table row actions, input adornments).
## UX/UI guidelines
House rules come from the `ux-guidelines` skill (writing, formatting, states,
where actions and feedback live). This section applies them to `ActionIcon`.
**Use it when**
- A single, universally understood icon communicates the action: close, edit, delete, more, expand, copy.
- Space is constrained: table row actions, toolbars, input adornments, card corners.
- The action repeats many times on the screen, so a text label would be noise.
**Use something else when**
| Need | Use instead |
| --- | --- |
| The action is the main thing on the surface, or the icon is ambiguous | Button with `icon` and a text label |
| Navigation to another page | Link / LinkButton |
| Several actions on one row | one ActionIcon that opens a Menu (`More actions`) |
| Decorative icon next to text | Icon |
**Do**
- Always pass `aria-label` as a verb + object: `Delete product`, `Close notification`, `Copy link`.
- Pair it with a Tooltip carrying the same text on pointer devices.
- Keep the destructive one last in a group and use the danger tone.
- Keep hit area ≥ 24×24 CSS px (the kit sizes do); prefer `md` for touch surfaces.
**Don't**
- Use icon-only actions for the page's primary action.
- Invent icons for abstract actions (`Sync`, `Reconcile`) — use a labelled Button.
- Put two different actions with similar icons side by side (edit pencil vs rename pencil).
- Disable an ActionIcon without explaining why elsewhere — tooltips don't show on disabled controls.
**Copy and states**
- The `aria-label` and Tooltip text follow button-label rules from ux-guidelines/ux-writing.
- Destructive icon actions still confirm or offer Undo (ux-guidelines/feedback-and-actions).
**Behaviour (from the UX spec)**
- The glyph is a prop: any `icon` that matches the action. The design file's fixed ✕ master and `Table.IconButton` are both this component.
- A close (✕) ActionIcon only closes; the host layer resolves unsaved drafts and returns focus. It never saves or deletes.
- There is no loading state; show progress on the row or surface the action changes.
**Figma → code**
| Figma | Code |
| --- | --- |
| fixed ✕ glyph | `icon` (any `token-icon-*` / `icon-[…]`) |
| `size=sm…lg`, `severity=neutral\|danger` | `size`, `severity` (same values) |
| — | `disabled` (removed from tab order) |
| `state=hover` | not a prop (browser state) |
| `Table.IconButton` | `ActionIcon` |
Full UX page (anatomy, states, behaviour, edge cases): [references/ux.md](references/ux.md). The same page renders in Storybook as *Atoms/ActionIcon → UX guidelines*.
## Accessibility
An icon-only control has no visible text, so it **must** carry an accessible name — pass
`aria-label` (or an equivalent labelling mechanism). Never ship an ActionIcon without one.
Since v1.1.0 the type enforces it: `ActionIconProps` requires `aria-label` or
`aria-labelledby`, so `` without a name no longer compiles.
When spreading Zag trigger props (typed with an optional `aria-label`), pass the
name explicitly: `aria-label={triggerProps["aria-label"] ?? "Next slide"}`.
## Styling
Use the component's own token classes; do not reach for semantic tokens or arbitrary Tailwind
values in app code. Size and tone are props, not ad-hoc classes.
Resting and disabled defaults sit below caller background utilities, so a parent
control can retain its own photo-overlay surface. Explicit disabled background
classes remain available for deliberate state overrides.
## Interaction and sizing contract
Sizes sm/md/lg use the shared **icon-control hit area**, not the full boxed-field
height: they are supporting actions embedded in fields and toolbars. Default md;
prefer lg for standalone touch actions. Disabled actions do not take hover or
pressed treatments and are removed from keyboard tab order. Every instance must
have `aria-label` or `aria-labelledby`; a glyph alone is not a name.
## Supported tone
`severity="neutral" | "danger"`, default `neutral`. Use `danger` for a destructive
supporting action, not a nonexistent `variant` prop. Sizes are `sm | md | lg`.
```tsx
import { ActionIcon } from "@techsio/ui-kit/atoms/action-icon"
```
The pressed danger foreground/background are an explicit paired set of
`--color-action-icon-{bg,fg}-danger-active` aliases; override both together.