NumberField

When to use

NumberField is for numbers that are not money: counts, days, percentages, order numbers. When the value changes in small steps, the decrement and increment buttons speed it up.

When not to use

• For amounts: use AmountInput; money travels as minor units in a bigint, never as a float.
• For digit strings such as phone numbers, IBANs or ID numbers: these are text, not numbers; use TextInput, PhoneInput or IbanInput.
• For a rough value across a wide range: use Slider.

Anatomy

Number of days (days)

days

Enter a value from 1 to 30.

LightDark

Copy code

import { NumberField } from '@bigbang/ui';

export default function WithUnit() {
  return (
    <NumberField
      className="max-w-xs"
      label="Number of days"
      unit="days"
      defaultValue={7}
      min={1}
      max={30}
      stepper={false}
      description="Enter a value from 1 to 30."
    />
  );
}

1. Label: label-md; the visible and accessible name of the field.
2. Box: The same as the TextInput box; 32, 36 or 40 px.
3. Unit: Optional short text such as “days”; added to the accessible name in brackets.
4. Step buttons: Decrease and Increase at the end of the box, set off by a thin line.
5. Description and error: Under the field.

Behaviour

• Typed text is read in the Provider language: 1.234,5 in Turkish, 1,234.5 in English.
• Arrow keys change the value by step, Page Up and Page Down by largeStep; Home and End jump to min and max.
• A value outside the range is moved to the nearest bound when focus leaves, and “Value changed to 30” is announced once.
• The step button at a bound is disabled. The buttons are not in the tab order; the arrow keys do the same on the keyboard.
• onValueChange runs while typing; onValueCommitted runs when focus leaves or a step ends.

Guidelines

• When the range matters, say it in the description: “Enter a value from 1 to 30.” Users should know the bounds before they type.
• Put the unit in unit, not in the label, so the label stays short.
• Pick a step that matches how the value naturally grows: 1 for counts, 0.5 points for a percentage.
• Changing the value with the scroll wheel is off, so the value does not change by accident while the page scrolls.

Content

• The label names what is measured: “Number of days”, “Quantity”.
• The error message states the range: “Value must be between 1 and 30.”

Turkish	English
Artır	Increase
Azalt	Decrease
Sayı alanı	Number field
Değer {value} olarak düzeltildi	Value changed to {value}

Related components

• TextInput: Free text.
• AmountInput: A money amount.
• Slider: A rough value in a range.