Skip to content

Documentation

IconButton

IconButton is the icon-only action variant built on the same button foundation as Button.

Storybook Source Figma

Root Props

Prop	Type	Default
`size`	`IconButtonSize`	`'md'`
Size of the button container. Controls padding and overall clickable area.
`asChild`	`boolean`	—
When true, renders the button as a child component using `Slot` (e.g., from Radix UI). Enables polymorphic rendering — useful for making the button act as a link or custom tag.
`variant`	`ButtonBaseVariant`	—
Defines the visual style of the button, affecting color schemes and emphasis.
`appearance`	`ButtonBaseAppearance`	—
Adjusts the button's structural appearance (background, border, etc.).
`disabled`	`boolean`	—
Disables the button when true. Prevents user interaction and applies a visually disabled state. Not applied with `asChild`: the child element owns its disabled state, for example, `aria-disabled` or a link without `href`.
`className`	`string`	—
Optional custom CSS class for the button element. Useful for design system overrides or scoped styles.
`children`	`ReactNode`	—
Content of the button — text, icon, or any React node.
`ref`	`Ref<HTMLButtonElement>`	—
Ref forwarded to the native `<button>` element. Allows direct DOM access for focus management or measuring.

Also accepts all <button> attributes.

Child Parts

IconButton does not expose public child parts.

Types

IconButtonProps
IconButtonSize

State Model

IconButton is mostly stateless from the component API perspective.
Disabled and icon-state behavior are usually driven by the consumer.
disabled is not applied with asChild, because the child element owns its semantics. A disabled link is an <a> without href; add aria-disabled="true" to get the disabled styling and announcement.
Accessible naming is the consumer’s responsibility because visible text is absent.