Loading…

Quantity Input

beta

A number with a unit: step it, switch between kg and lb or GB and TB with the amount converted, or type "5 lb".

Forms
3 files
1 npm package
Accessibility notes

Playground

Installation

One command and the file is in your project, or copy it in by hand.

$pnpm dlx @dowel-ui/cli add quantity-input

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 { QuantityInput } from "@/components/ui/quantity-input";

Examples

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

Default
Storage Size
Temperature
Duration
German Locale

API

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

<QuantityInput>

Prop	Type	Default
`units` (required) The units offered, all of one dimension. The first is the default.	`readonly QuantityUnit[]`	—
`convertOnUnitChange` Converts the amount when the unit changes (5 kg → 11.02 lb). Off, the number stays.	`boolean`	`true`
`defaultValue` Initial value when uncontrolled. Defaults to 0 in the first unit, within the bounds.	`Quantity`	—
`disabled`	`boolean`	`false`
`inputRef` Ref to the text field, for focusing it. A form library's field ref goes here.	`Ref<HTMLInputElement>`	—
`inputSize`	`"sm" \| "md" \| "lg"`	`"md"`
`label` Visible label, linked to the field. Without it, pass aria-label or aria-labelledby.	`ReactNode`	—
`labels` Replaces any of the field's own copy.	`Partial<QuantityInputLabels>`	—
`largeStep` Steps taken by Shift+Arrow and Page Up/Down.	`number`	`10`
`locale` Locale for writing and reading numbers. Defaults to the browser's, used once hydrated: the server and hydration write en-US, so the two agree.	`string`	—
`max` Highest quantity, in any of the units.	`Quantity`	—
`min` Lowest quantity, in any of the units. It follows the field into whichever unit is chosen.	`Quantity`	—
`name` Submits the amount under this name, as a plain number ("11.02").	`string`	—
`onValueChange` Called with each committed change: a step, a unit change, or typed text on blur or Enter.	`(value: Quantity) => void`	—
`readOnly`	`boolean`	`false`
`step` Step for every unit. Leave unset to use each unit's own step, or 1.	`number`	—
`unitName` Submits the unit's value under this name. Defaults to `${name}Unit`.	`string`	—
`value` Controlled value.	`Quantity`	—

Plus every attribute of <div> except defaultValue, onChange, children.

Accessibility

The field is a text input with role="spinbutton", aria-valuenow, -valuemin and -valuemax in the current unit, and an aria-valuetext that spells the unit out ("2.5 kilograms", "1 kilogram" where the locale's plural rules say one), because an abbreviation read aloud is often just letters. Up and Down step, Shift+Arrow and Page Up/Down take ten steps, Home and End jump to the bounds when there are any; Left and Right are left to the caret. The − and + buttons are named with the step and unit ("Decrease by 0.1 kg") and stay out of the Tab order, since the arrow keys do the same from the field, so Tab goes field, then unit. The unit is a native select named after the field ("Parcel weight unit"), so it has the platform's keyboard model and picker. Text that cannot be read is kept on screen with aria-invalid, a message that says what to type, and the same message as the field's custom validity; the value stays at the last good one. The message is text with an icon, never colour alone, and arrives in a polite live region that is present and empty from the start, so it is announced once on blur or Enter rather than while typing. Escape discards the text. A development warning fires when the field has no accessible name.

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

units

The units offered, all of one dimension. The first is the default.

readonly QuantityUnit[]

—

convertOnUnitChange

Converts the amount when the unit changes (5 kg → 11.02 lb). Off, the number stays.

boolean

true

defaultValue

Initial value when uncontrolled. Defaults to 0 in the first unit, within the bounds.

Quantity

—

disabled

boolean

false

inputRef

Ref to the text field, for focusing it. A form library's field ref goes here.

Ref<HTMLInputElement>

—

inputSize

"sm" | "md" | "lg"

"md"

label

Visible label, linked to the field. Without it, pass aria-label or aria-labelledby.

ReactNode

—

labels

Replaces any of the field's own copy.

Partial<QuantityInputLabels>

—

largeStep

Steps taken by Shift+Arrow and Page Up/Down.

number

10

locale

Locale for writing and reading numbers. Defaults to the browser's, used once hydrated: the server and hydration write en-US, so the two agree.

string

—

max

Highest quantity, in any of the units.

Quantity

—

min

Lowest quantity, in any of the units. It follows the field into whichever unit is chosen.

Quantity

—

name

Submits the amount under this name, as a plain number ("11.02").

string

—

onValueChange

Called with each committed change: a step, a unit change, or typed text on blur or Enter.

(value: Quantity) => void

—

readOnly

boolean

false

step

Step for every unit. Leave unset to use each unit's own step, or 1.

number

—

unitName

Submits the unit's value under this name. Defaults to ${name}Unit.

string

—

value

Controlled value.

Quantity

—