IconButton

Status: Experimental

IconButton is for familiar, compact actions where a visible text label would add unnecessary repetition. Its label prop is required and becomes the accessible name.

Preview

Basic usage

---
import { IconButton, SearchIcon } from '@freightpx/frasto';
---

<IconButton icon={SearchIcon} label="Search customers" />

The icon is decorative to assistive technology because the button itself owns the accessible label.

Variants and sizes

Icon buttons are always square: 32px, 36px, or 40px. They never use a circular or rounded container.

Loading, disabled, and danger

Navigation

Provide href when the icon moves to another location:

<IconButton
  icon={ArrowUpRightIcon}
  label="Open report"
  href="/reports/monthly"
/>

API

Prop	Type	Default	Purpose
icon	Lucide Astro component	required	rendered icon
label	string	required	accessible control name
variant	'solid' | 'outline' | 'ghost'	'ghost'	visual emphasis
tone	'neutral' | 'danger'	'neutral'	semantic risk
size	'sm' | 'md' | 'lg'	'md'	square control size
type	'button' | 'submit' | 'reset'	'button'	native button behavior
href	string	—	renders an anchor for navigation
loading	boolean	false	prevents activation and shows progress
disabled	boolean	false	prevents activation
class	string	—	adds a consumer class

Accessibility

• label is mandatory even if a visual tooltip will be added later.
• Use familiar icons consistently across the product.
• Do not rely on a browser title attribute as the accessible name.
• Pair unfamiliar actions with visible text using Button.
• Keep the focus outline distinct from hover, selected, and active states.
• When tooltips are introduced, the tooltip text should match the accessible label.

When not to use it

Do not turn every toolbar action into an icon. If people may need to interpret or learn the action, use a labeled Button instead.