Number input
The kit input as a number field, with the browser’s number semantics.
On this page
Code
import { NumberInput } from "@bosunkit/components/number-input";
import type { ReactElement } from "react";
export const description: string =
"A number field with the browser's semantics — spin buttons, a digit keyboard on a phone, min, max and step.";
export default function Depth(): ReactElement {
return <NumberInput aria-label="Depth" unit="m" min={0} max={300} step={0.1} defaultValue="4.2" />;
}
Choosing a numeric field
Use NumberInput for a quantity with a numeric range and step. Use a text-based input for identifiers, codes, phone numbers and values whose leading zeroes matter. A slider suits approximate adjustment; a number field suits an exact entered value. Put the field in FormField for a visible label, hint and associated error.
Drafts, bounds and validation
The component wraps the native number input. onChange receives the browser event, and the draft stays text
while editing. Clearing the field produces an empty string; it must not become zero. Parse a finite value at
the consumer's validation boundary and retain the draft when validation fails.
A paste is read before the browser sees it, because the browser drops the characters a number cannot hold and keeps the rest: "4,2" would become 42. A decimal comma is read as the point, so "4,2" is 4.2. A paste the field cannot read as one number leaves the field as it was: grouped figures ("1.234,5"), a unit ("12.5 kn"), and a point or a comma before exactly three digits ("1,234"), which is 1234 in one language and 1.234 in another.
min, max and step participate in native constraint validation. They do not clamp arbitrary typed values
or authorize a setting on the server. State the unit and allowed range, validate again at the save boundary,
and show the confirmed value only after a successful save. Read-only preserves inspection; disabled makes the
control unavailable. Test typing, clearing and the browser's step controls as well as the initial value.
Enter a whole number from one to twelve.
This example is read-only.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| className | string | undefined | – | Additional input classes. |
| ref | Ref<HTMLInputElement> | undefined | – | The input element. |
| icon | ReactNode | undefined | – | An icon inside the field's left edge, before the text, such as a magnifier on a search field. It is decorative: the field's label says what it is for. |
| unit | string | undefined | – | The unit of the value, inside the field's right edge (m, kn, °T), as SN.1/Circ.243 writes it. It is read
after the value, through aria-describedby, so the field's name need not repeat it. |
| onValueChange | ((value: string, eventDetails: Input.ChangeEventDetails) => void) | undefined | – | Callback fired when the value changes. Use when controlled. |
| defaultValue | Field.Control.Props['defaultValue'] | undefined | – | The default value of the input. Use when uncontrolled. |
| value | React.ComponentProps<'input'>['value'] | undefined | – | The value of the input. Use when controlled. |
| render | React.ReactElement | ComponentRenderFn<RenderFunctionProps, State> | undefined | – | Allows you to replace the component's HTML element
with a different tag, or compose it with another component.
Accepts a ReactElement or a function that returns the element to render. |
| style | React.CSSProperties | ((state: State) => React.CSSProperties | undefined) | undefined | – | Style applied to the element, or a function that returns a style object based on the component's state. |
Also takes every attribute of Omit<InputProps, "type">.
Related
- Form field: visible labels, hints and validation associations.
- Interaction states: pending, disabled, read-only and invalid behavior.
- Content: names, quantities and useful messages.