Stable

Icon Button

Icon buttons help people take minor actions, often used in app bars and toolbars where space is tight. ButtonIcon shares the same emphasis levels as Button, and can optionally act as a toggle with a pressed state.

M3 Spec
open_in_new

Overview

The ButtonIcon component implements the Material Design 3 Icon Buttons pattern: standard, filled, tonal, and outlined emphasis levels, all icon-only.

Because there's no visible label, always pass tooltipContent — it's wrapped in a Tooltip internally, giving both a visual hint on hover and a text alternative for assistive tech. Set variation="toggle" for a two-state icon button (e.g. bookmark, mute) — it swaps the underlying element for Bits UI's Toggle.Root.

Import

import { ButtonIcon } from '@noxlovette/material';

Live Demo

See it live, with Controls, in Storybook rather than a hand-rolled preview here.

widgets

Playground

Variant, color, size, width, and variation Controls.
widgets

Toggle

A two-state toggle icon button.

Basic Usage

Always pair the icon with tooltip text to describe the action:

<script lang="ts">
  import { ButtonIcon } from '@noxlovette/material';
</script>

<ButtonIcon
  variant="tonal"
  iconProps={{ name: 'search' }}
  tooltipContent="Search"
/>

<!-- Toggle variation -->
<ButtonIcon
  variation="toggle"
  iconProps={{ name: 'bookmark' }}
  tooltipContent="Save"
/>

ButtonIcon Props

PropTypeDefaultDescription
iconProps required
IconProps—Passed directly to the Icon component.
variant
"elevated" | "filled" | "tonal" | "outlined" | "text" | "bare""text"Visual emphasis. "text" (the standard icon button) is the default and lowest emphasis.
color
"default" | "primary" | "secondary" | "tertiary" | "error""default"Color role. "default" resolves to the same styling as "primary".
size
"xs" | "sm" | "md" | "lg" | "xl""md"Controls height, padding, and icon size.
width
"default" | "narrow" | "wide""default""default" keeps the button square (aspect-square); narrow/wide adjust the horizontal footprint.
shape
"round" | "square""round"Fully rounded or slightly rounded corners.
variation
"default" | "toggle""default""toggle" renders a Bits UI Toggle.Root with a pressed/unpressed visual state instead of a plain button.
pressed
booleanfalseOnly meaningful when variation="toggle". Bindable pressed state.
onPressedChange
(pressed: boolean) => void—Only meaningful when variation="toggle". Fires when the pressed state changes.
tooltipContent
string—Text shown in a tooltip on hover. Icon buttons have no visible label, so this is the primary way to convey the action.
triggerSide
"top" | "right" | "bottom" | "left""top"Side of the tooltip relative to the button.
triggerAlign
"start" | "center" | "end""center"Alignment of the tooltip relative to the button.
disabled
booleanfalseDisables the button.
loading
booleanfalseShows a LoadingIndicator in place of the icon.
href
string—Renders the button as an <a> instead of a <button>.

Accessibility

label

Accessible name

tooltipContent doubles as the only visible/announced description of the action — always provide it since there is no text label.

toggle_on

Toggle semantics

variation="toggle" uses Bits UI's Toggle.Root, which exposes aria-pressed for the pressed/unpressed state.

block

Disabled state

disabled removes the button from the tab order and exposes the disabled attribute to assistive tech.