Loading…

Flip Button

beta

A button with a front and a back face that turns over in 3D on a spring — on hover and focus, or as a toggle on press.

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 flip-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 { FlipButton } from "@/components/ui/flip-button";

Examples

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

Default
Axes
Press Toggle
Surfaces

API

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

<FlipButton>

Prop	Type	Default
`back` (required) The face shown once turned over. Decorative: it is aria-hidden.	`ReactNode`	—
`axis`	`"y" \| "x"`	`"y"`
`backClassName` Classes for the back face.	`string`	—
`backVariant` Button surface for the back face. Defaults to `secondary`.	`FaceVariant`	`"secondary"`
`defaultFlipped` Initial turned-over state when uncontrolled (`trigger="press"`).	`boolean`	`false`
`flipped` Controlled turned-over state. Works with either trigger.	`boolean`	—
`front` The face shown at rest. Names the button. Falls back to `children`.	`ReactNode`	—
`frontClassName` Classes for the front face.	`string`	—
`onFlippedChange` Called with the new state when a press turns the button.	`(flipped: boolean) => void`	—
`shape`	`"default" \| "pill" \| "square"`	`"default"`
`size`	`"sm" \| "md" \| "lg" \| "icon" \| "icon-sm"`	`"md"`
`trigger`	`"hover" \| "press"`	`"hover"`
`variant` Button surface for the front face.	`FaceVariant`	`"primary"`
`children` The front face, when `front` is not given.	`ReactNode`	—

Plus every attribute of <button> except children.

Accessibility

The accessible name is the front face; the back face is aria-hidden, so the name never changes under a screen reader. With trigger="press" the button is a toggle exposed through aria-pressed; with trigger="hover" it also turns on keyboard focus-visible, and the turn is purely decorative. Pass aria-label when the front face has no text. Under reduced motion the turn becomes an instant swap.

Quality

Measured from the source and its tests at build time.

All scores

10/10

checks passed

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

Prop

Type

Default

back

The face shown once turned over. Decorative: it is aria-hidden.

ReactNode

—

axis

"y" | "x"

"y"

backClassName

Classes for the back face.

string

—

backVariant

Button surface for the back face. Defaults to secondary.

FaceVariant

"secondary"

defaultFlipped

Initial turned-over state when uncontrolled (trigger="press").

boolean

false

flipped

Controlled turned-over state. Works with either trigger.

boolean

—

front

The face shown at rest. Names the button. Falls back to children.

ReactNode

—

frontClassName

Classes for the front face.

string

—

onFlippedChange

Called with the new state when a press turns the button.

(flipped: boolean) => void

—

shape

"default" | "pill" | "square"

"default"

size

"sm" | "md" | "lg" | "icon" | "icon-sm"

"md"

trigger

"hover" | "press"

"hover"

variant

Button surface for the front face.

FaceVariant

"primary"

children

The front face, when front is not given.

ReactNode

—