SpinButton

SpinButton lets people type a number and step it up or down with buttons or the keyboard.

Two stacked arrow buttons on the right (press and hold to repeat). Keyboard: ↑/↓ by step, PageUp/PageDown by stepPage, Home/End to min/max, Enter to commit a typed number. The value is always clamped to [min, max].

Quantity

Import

Install from npm, copy the source into your project with @yugen-ui/cli or the shadcn CLI, or import directly when working in this repo.

TSX

// npm install yugen-uiimport { SpinButton } from "yugen-ui";

Variants

Each tile is a standalone example: hover to copy, or press Code to see the source.

Decimal step

step={0.1}: the number of decimal places is derived from step.

Display format

formatValue adds a unit; non-numeric characters are ignored while typing.

Room for 2 guests

Controlled

value / onValueChange (null when the input is empty).

Appearance, size & disabled

outline, underline, filled-darker, filled-lighter; size small / medium.

Usage

Use it for small numbers that change in small steps (quantity, number of guests, font size).
Always set a sensible min/max to rule out meaningless values.
Show the unit with formatValue rather than in the label, where that fits.

Don't

Don't use it for large numbers or values that don't change in steps (phone numbers, postal codes). Use Input.
Don't use it when the relative value matters more than the exact number. Use Slider.

Props

Prop · Type	Default	Description
value / defaultValuenumber \| null	Default: —	Numeric value (null = empty).
onValueChange(value: number \| null) => void	Default: —	Called when the value changes.
min / maxnumber	Default: —	Limits; the matching button is disabled at the limit.
step / stepPagenumber	Default: 1 / step × 10	Step for ↑↓ and for PageUp/PageDown.
precisionnumber	Default: —	Number of decimal places (derived from step by default).
displayValuestring	Default: —	Text shown instead of the number (controlled).
formatValue / parseValue(v: number) => string / (text: string) => number \| null	Default: —	Custom number formatting and parsing.
appearance"outline" \| "underline" \| "filled-darker" \| "filled-lighter"	Default: "outline"	Control style.
size"small" \| "medium"	Default: "medium"	Height 24 / 32px.

Messages

Text built into the component: labels, aria-labels, screen reader announcements.

English by default. Change it with the messages prop of YugenProvider, by the namespace below; messagesVi has the Vietnamese set. See Interface language.

messages.spinButton

Key · Type	Default (English)	messagesVi
incrementstring aria-label nút tăng.	Default (English)`"Increment value"`	messagesVi`"Tăng giá trị"`
decrementstring aria-label nút giảm.	Default (English)`"Decrement value"`	messagesVi`"Giảm giá trị"`