Loading…

Morph Button

beta

A button whose icon and label morph to an active state — toggles, transient confirmations and hover affordances.

Forms
1 file
1 npm package
Accessibility notes

Playground

Installation

The CLI installs button as well, because this component imports it. Or copy everything in by hand.

$pnpm dlx @dowel-ui/cli add morph-button

npm packages installed: class-variance-authority.

Usage

Imported from your own path — the file is yours, so this is an import like any other.

app/page.tsxTSX

import { MorphButton } from "@/components/ui/morph-button";

Examples

Every example the tests run, live and operable, side by side.

Default
Gallery
Icon Only
Morphs
Transient
Hover

API

Generated from the component's own types, so a prop cannot appear here without existing.

<MorphButton>

Prop	Type	Default
`icon` (required) The resting icon. Decorative: it is hidden from assistive technology.	`ReactNode`	—
`active` Controlled active state.	`boolean`	—
`activeIcon` The icon shown while active. Defaults to `icon`, for fill/colour-only morphs.	`ReactNode`	—
`activeLabel` Text shown while active, e.g. "Copied". Defaults to `label`.	`ReactNode`	—
`adornment` Decoration that pops in with the active icon.	`"none" \| "sparkle" \| "dot"`	`"none"`
`announcement` Announced when a `transient` button activates. Defaults to `activeLabel`.	`string`	—
`defaultActive` Initial active state when uncontrolled.	`boolean`	`false`
`fillOnActive` Fills the active icon with its stroke colour — bookmark, like, favourite.	`boolean`	`false`
`label` Visible text beside the icon. Without it the button is icon-only and must be named with `aria-label` or `aria-labelledby`.	`ReactNode`	—
`morph`	`"scale" \| "rise" \| "tilt"`	`"scale"`
`onActiveChange` Called whenever the active state changes, from any trigger.	`(active: boolean) => void`	—
`revertAfter` Milliseconds before a `transient` button reverts.	`number`	`2000`
`tone`	`"current" \| "primary" \| "success" \| "warning" \| "destructive" \| "info"`	`"current"`
`trigger` What drives the active state. - `toggle` (default): each press flips it; exposed as `aria-pressed`. - `transient`: a press activates it, and it reverts after `revertAfter`. The active label is announced through a polite live region. - `hover`: active while hovered or focused, for parity with the demo. - `manual`: only the `active` prop changes it.	`MorphButtonTrigger`	`"toggle"`

Accessibility

In `toggle` mode the state is exposed with aria-pressed and the accessible name stays the resting label, so "Mute" never becomes "Unmute, pressed". `transient` confirmations (Copied, Submitted) are announced through a polite live region and revert on a timer. `trigger="hover"` activates on keyboard focus as well as hover. Icons are aria-hidden: an icon-only button must be named with aria-label or aria-labelledby, and warns in development when it is not. Motion stops under reduced motion.

Quality

Measured from the source and its tests at build time.

All scores

8/8

checks passed

Tested — passes
axe assertion — passes
Keyboard tested — does not apply
Storybook examples — passes
Accessibility documented — passes
Semantic tokens only — passes
Motion from tokens — passes
className merged — passes
Visible focus — does not apply
No fixed widths — passes

Prop

Type

Default

icon

The resting icon. Decorative: it is hidden from assistive technology.

ReactNode

—

active

Controlled active state.

boolean

—

activeIcon

The icon shown while active. Defaults to icon, for fill/colour-only morphs.

ReactNode

—

activeLabel

Text shown while active, e.g. "Copied". Defaults to label.

ReactNode

—

adornment

Decoration that pops in with the active icon.

"none" | "sparkle" | "dot"

"none"

announcement

Announced when a transient button activates. Defaults to activeLabel.

string

—

defaultActive

Initial active state when uncontrolled.

boolean

false

fillOnActive

Fills the active icon with its stroke colour — bookmark, like, favourite.

boolean

false

label

Visible text beside the icon. Without it the button is icon-only and **must** be named with aria-label or aria-labelledby.

ReactNode

—

morph

"scale" | "rise" | "tilt"

"scale"

onActiveChange

Called whenever the active state changes, from any trigger.

(active: boolean) => void

—

revertAfter

Milliseconds before a transient button reverts.

number

2000

tone

"current"

trigger

What drives the active state. - toggle (default): each press flips it; exposed as aria-pressed. - transient: a press activates it, and it reverts after revertAfter. The active label is announced through a polite live region. - hover: active while hovered *or* focused, for parity with the demo. - manual: only the active prop changes it.

MorphButtonTrigger

"toggle"