RoadieRoadie
  • Home
  • Brand
  • Foundations
  • Content
  • Tokens
  • Components
  • Charts
  • Widgets
  • Appearance
HomeBrandFoundations
Appearance

Components

  • Navigation

    • Breadcrumb
    • LinkBeta
    • NavigatorAlpha
    • Steps
    • Tabs

  • Layout

    • Accordion
    • CollapsibleBeta
    • PaneAlpha
    • ScrollArea
    • Separator

  • Actions

    • Button
    • IconButton
    • ToggleBeta
    • Toggle groupBeta
    • ToolbarBeta

  • Fields

    • EditorAlpha
    • Field
    • Fieldset
    • Input
    • Label
    • Number fieldBeta
    • OTP fieldBeta
    • Query fieldAlpha
    • Textarea

  • Choices

    • Autocomplete
    • CheckboxBeta
    • Combobox
    • Radio group
    • Select
    • SliderBeta
    • SwitchBeta

  • Date and time

    • CalendarBeta
    • CalendarTile
    • Countdown
    • Dashboard periodBeta
    • Date fieldBeta
    • Date pickerBeta
    • Date range pickerBeta
    • DateTime
    • Duration
    • Time fieldBeta

  • Collections

    • Card
    • Carousel
    • DataTableBeta
    • ListAlpha
    • Marquee
    • RecordGridAlpha
    • RecordTableAlpha
    • SortableAlpha
    • TableBeta

  • Overlays

    • Dialog
    • Drawer
    • MenuBeta
    • Popover
    • ToastBeta
    • Tooltip

  • Status

    • Badge
    • CalloutBeta
    • DeltaBeta
    • Empty state
    • MeterBeta
    • ProgressBeta
    • SkeletonBeta
    • SparklineBeta
    • StatTileBeta

  • Media & brand

    • AvatarBeta
    • Icon Tile
    • Image
    • Logo
    • PatternBeta
    • QR codeBeta
    • SpotIllustration

  • Text

    • Code
    • Highlight
    • KbdBeta
    • Mark
    • Prose

IconButton

Status
Stable
Added
Components 0.1.03 Jan 2025
Updated
Components 2.16.020 Oct 2026
Docs updated
19 Oct 2026

A square button for icon-only actions.

Import

import { IconButton } from '@oztix/roadie-components'

Examples

Default

Always provide an aria-label since there is no visible text.

<IconButton aria-label='Add item'>
  <Plus weight='bold' />
</IconButton>

Emphasis

<IconButton aria-label='Strong' emphasis='strong'>
  <Star weight='bold' />
</IconButton>
<IconButton aria-label='Normal' emphasis='normal'>
  <Star weight='bold' />
</IconButton>

Sizes

The default size is md. All sizes maintain square proportions.

<IconButton aria-label='Extra small' size='xs'>
  <Heart weight='bold' />
</IconButton>
<IconButton aria-label='Small' size='sm'>
  <Heart weight='bold' />
</IconButton>

The legacy icon-xs / icon-sm / icon-md / icon-lg size literals are still accepted for backwards compatibility (marked @deprecated in TypeScript) but new code should use the plain xs / sm / md / lg names above.

Intents

{/* Strong */}
<IconButton aria-label='Neutral' emphasis='strong' intent='neutral'><CheckCircle weight='bold' /></IconButton>
<IconButton aria-label='Accent' emphasis='strong' intent='accent'><CheckCircle weight='bold' /></IconButton>
<IconButton aria-label='Brand' emphasis='strong' intent='brand'><CheckCircle weight='bold' /></IconButton>
<IconButton aria-label='Info' emphasis='strong' intent='info'><CheckCircle weight='bold' /></IconButton>
<IconButton aria-label='Success' emphasis='strong' intent='success'><CheckCircle weight='bold' /></IconButton>

States

{/* Default */}
<IconButton aria-label='Favorite'><Heart weight='bold' /></IconButton>
{/* Disabled */}
<IconButton aria-label='Favorite' disabled><Heart weight='bold' /></IconButton>

Href

Pass href to render the icon button as a routed anchor. Roadie picks the right element + safety attributes based on the href shape: internal routes go through your configured RoadieLinkProvider; external (https://…) auto-render with target='_blank' rel='noopener noreferrer'; protocol hrefs (mailto: / tel: / sms:) render plain anchors.

{/* Internal */}
<IconButton aria-label='View cart' href='/cart' emphasis='strong' intent='accent'>
  <ShoppingCart weight='bold' />
</IconButton>
{/* External */}
<IconButton aria-label='Open Oztix in a new tab' href='https://oztix.com.au' emphasis='normal'>

Hover each button. The browser status bar shows the resolved href exactly as Roadie rendered it (note the mailto: / tel: URLs vs the routed paths). See Linking for the full reference, including external / target / rel overrides.

Download

Add download to an href icon button to save the file instead of opening it, optionally under a filename.

<IconButton aria-label='Download spec' href='/spec.pdf' download='spec.pdf'>
  <Download weight='bold' />
</IconButton>

Escape hatch

For full element control, or anchor props href doesn't cover (hreflang, referrerPolicy), use Base UI's render prop. It keeps Base UI's button semantics, role='button' and Space activation, so the element you pass is yours to make accessible. Passing both href and render triggers a one-shot dev warning. render wins, and provider routing is silently disabled.

Guidelines

  • Always provide an aria-label to describe the action since there is no visible text. Interface copy says how to word it.
  • For icon links that navigate, prefer <IconButton href={…}> and wire RoadieLinkProvider at the app root. The legacy LinkIconButton component is @deprecated and will be removed in v3.0.0.

API reference

IconButton

intent"neutral" | "brand" | "brand-secondary" | "brand-blue" | "brand-orange" | "brand-purple" | "accent" | "danger" | "success" | "warning" | "info" | null
emphasis"strong" | "normal" | "subtle" | "subtler" | null
classNamestring | ((state: ButtonState) => string)

CSS class applied to the element, or a function that returns a class based on the component's state.

hrefstring

Pass a URL to render the button as a routed anchor instead of a `<button>`. Internal hrefs route through the configured `RoadieLinkProvider` (or fall back to plain `<a>`); external hrefs (`http(s)://`, `//…`) render as `<a target='_blank' rel='noopener noreferrer'>`; `mailto:` / `tel:` / `sms:` render as plain `<a>`. Pair with `external`, `target`, or `rel` to override the defaults.

externalboolean

Force external-link treatment regardless of `href` shape. Useful for first-party URLs that should still open in a new tab, or for an `https://` URL that should route internally through the provider.

targetstring

Override the auto `target='_blank'` default on external hrefs.

downloadstring | boolean

Download the `href` instead of navigating, optionally as this filename.

aria-labelstring
Required
size"xs" | "sm" | "md" | "lg" | "icon-xs" | "icon-sm" | "icon-md" | "icon-lg"

Icon-button sizing. Use `'xs' | 'sm' | 'md' | 'lg'` (plain) — the `'icon-*'` aliases are accepted for backwards compatibility but discouraged.

Defaults to md.

Inherited from HTMLAttributes

relstring

Override the auto `rel='noopener noreferrer'` default on external hrefs.

Inherited from ButtonProps

focusableWhenDisabledboolean

Whether the button should be focusable when disabled.

Defaults to false.

Inherited from NativeButtonProps

nativeButtonboolean

Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`).

Defaults to true.

Previous page← ButtonNext pageToggle →