Skip to content
flyingsalmon

Number field

A quantity field that formats for the page’s locale, clamps to its bounds, and steps from the keyboard or its own spin buttons.

Installation

npx shadcn@latest add @flyingsalmon/number-field

Usage

import { useState } from 'react'

import { NumberField } from '@/components/ui/number-field'

export function NumberFieldUsage() {
  const [travellers, setTravellers] = useState<number | null>(2)

  return (
    <NumberField
      label="Travellers"
      value={travellers}
      onValueChange={setTravellers}
      min={1}
    />
  )
}

Examples

Budget with a prefix

prefix puts a symbol before the value and step sizes one press of a spin button. The prefix is plain text, so it reads the way your product writes money, and the value still groups for the locale.

Duration with a unit

Home jumps to min and End to max, and each spin button dims as its end arrives.

Sizes

Two sizes match Input, so a number field and a text field line up in a row.

Description

Helper text shows the other view of the amount: the group total for a per-person budget. Step below $100 and the error grows in beneath it.

$7,200 for 4 travellers

Error

The border, the dividers, and the label turn destructive together.

Book for at least one traveller

Loading

Change the budget. A spinner replaces the spin buttons in exactly their width while the trips are counted, and the field stays typeable.

Disabled

The spin buttons stay in place and dim with the field, so the control never changes shape as it locks.

Read-only

The value stays readable and copyable, and the field still posts with its form.

Guidelines

When to use

  • For a quantity the traveller adjusts: travellers, nights, a budget.
  • When the value is arithmetic input and the field must report a number, with bounds you can enforce.

When not to use

  • Use Input for a numeric string nothing does arithmetic on, such as a booking reference or a phone number.
  • Use Slider when the traveller sets an approximate value on a range and the exact figure does not matter.

Do and don’t

  • Do
    Give every quantity its unit: "$" before a budget, "people" after a group size.The number reads as a phrase, so nobody wonders whether 4 means nights or travellers.
  • Do
    Bound the field by the real limits of what it counts, such as 2 to 30 people.The field and its spin buttons refuse the impossible as the traveller enters it, so no error has to arrive afterwards.
  • Don’t
    Stretch the field across the form column.A quantity is a few digits. A field sized to its number reads as a count; a wide one looks like it wants a sentence.
  • Do
    Offer a slider beside the exact entry when "roughly" is a fair answer, and let the traveller swap between them.A traveller who knows the figure types it, and one who does not can still answer without guessing a precise number.
  • Don’t
    Lock the field while a background check runs.A spinner takes the place of the spin buttons and the field stays typeable. Only the submit button locks a flow.

Accessibility

KeyDescription
TabMoves focus into the field and then out. The spin buttons are outside the tab order, because the arrow keys already do their job.
ArrowUpArrowDownSteps the value by step.
PageUpPageDownShift+ArrowUpShift+ArrowDownSteps the value by largeStep, ten times step unless you set it.
HomeEndJumps to min or max. Does nothing when that bound is unset.
EnterCommits the typed text and lets the form submit.
EscapeDoes nothing here, so it still closes an enclosing dialog.

The mouse wheel never steps the value, so scrolling through a form cannot change an answer. The text input is the spinbutton. Its value text includes the prefix and the unit, so a screen reader hears “$1,500” rather than “1500”, and an empty field omits its value attributes instead of announcing a number it does not have. The spin buttons are named Decrease and Increase. required marks the label and sets aria-required; the validation itself stays with your app. The states every field shares are described on Fields.

API

NumberField

Also takes every <input> attribute except type, size, and the value props it redefines. className styles the wrapper, so a width set there sizes the whole field.

PropTypeDefaultDescription
labelstring–The visible label. Renders above the field and is wired to it.
valuenumber | null–The controlled value. null is an empty field, never NaN or 0, so a blank and a zero stay apart.
defaultValuenumber | null–The initial value of an uncontrolled field.
onValueChange(value: number | null) => void–Reports the parsed number while typing, in range or not, and null when the field is empty. It is always a plain number, so read it rather than the typed text, which carries the locale’s group separator. Blur and Enter clamp into [min, max] and reformat.
minnumber–The floor. Set it on every count that cannot go negative: it bounds the clamp, gives Home somewhere to jump, disables Decrease at the floor, and picks the numeric mobile keyboard when it is zero or above.
maxnumber–The ceiling.
stepnumber1One arrow key or spin button press. A fractional step picks the decimal keyboard.
largeStepnumberstep * 10One Page Up, Page Down, or shifted arrow press.
prefixstring–Plain text before the value, such as "$".
unitstring–Plain text after the value, such as "days".
localestring–The locale for grouping and the decimal mark. Defaults to the page’s language.
sizeNumberFieldSizeNumberFieldSize.DefaultDefault and Small match the field heights of the same names.
descriptionstring–Helper text under the field.
errorstring–The failure message. Turns the border, the ring, and the label destructive. Text the parser cannot read reverts to the last value without raising one.
loadingbooleanfalseReplaces the spin buttons with a spinner. The field stays typeable. Set it, not disabled, while a background check runs.
disabledbooleanfalseDims the field, takes no pointer events, and posts nothing.
readOnlybooleanfalseKeeps the value readable and focusable. The field still posts.

  • Fields

    The label, description, error, loading, and disabled behaviour every field shares.
  • Input

    The single-line field for text that is not a quantity.
  • Slider

    Picks a value on a range by dragging.
  • Form

    Lays fields out with an actions row and a result slot.