Number Field

React Number Field components allow users to enter a numeric value with increment and decrement controls. They are commonly used in shopping carts, booking flows, inventory forms, and any scenario requiring precise numeric input with quick adjustments.

Quantity

Enter a quantity between 0 and 100.

Installation

The Number Field relies on the react-aria-components library.

Install the component using the Tailgrids CLI.

npx @tailgrids/cli add number-field

Anatomy

import { FieldDescription, FieldLabel } from "@/registry/core/field";
import { Input } from "@/registry/core/input";
import {
  NumberField,
  NumberFieldAction,
  NumberFieldGroup
} from "@/registry/core/number-field";
import { Minus, Plus } from "@tailgrids/icons";

export const NumberFieldExample = () => (
  <NumberField>
    <FieldLabel>Quantity</FieldLabel>

    <NumberFieldGroup>
      <Input placeholder="0" />
      <NumberFieldAction slot="decrement">
        <Minus />
      </NumberFieldAction>
      <NumberFieldAction slot="increment">
        <Plus />
      </NumberFieldAction>
    </NumberFieldGroup>

    <FieldDescription>Enter a quantity between 0 and 100.</FieldDescription>
  </NumberField>
);

Examples

Basic Usage

A standard number field implementation with increment and decrement buttons for adjusting a numeric value.

Quantity

Choose the number of items to purchase.

Controlled

Manage the numeric value externally using the value and onChange props.

Number of guests: 4

Uncontrolled

An uncontrolled number field with a defaultValue prop.

Table capacity

Maximum number of seats per booking.

With Step

Set a custom step value for fractional or non-standard increments.

Product rating

Rate in steps of 0.5 stars.

Validation

Display error messages and validation states when the numeric value falls outside the allowed range.

Age

Must be between 18 and 120.

Form Validation

Use a custom validate function for more control over error messages.

Format Options

Leverage the formatOptions prop to display numeric values as currency, percentages, or grouped decimals.

Price (currency)

Discount (percentage)

Annual salary (decimal)

Custom Icons

You can use any icons inside <NumberFieldAction> components. This example uses custom increment and decrement icons for a unique look.

Priority level

Rate the importance of this task.

Chevron Buttons (Right Aligned)

Position the action buttons according to your design needs.

Rating

Rate this product from 0 to 10.

API Reference

NumberField

The numeric input component with stepper buttons. Wraps React Aria's NumberField and maps boolean props (disabled, readOnly, required, invalid) to their is-* equivalents.

Prop	Type	Default	Description
`value`	`number`	-	The current value (controlled).
`defaultValue`	`number`	-	The default value (uncontrolled).
`onChange`	`(value: number) => void`	-	Handler called when the value changes.
`name`	`string`	-	The name of the input, used when submitting an HTML form.
`form`	`string`	-	The `<form>` element to associate the input with.
`id`	`string`	-	The element's unique identifier.
`autoFocus`	`boolean`	`false`	Whether the input should receive focus on mount.
`minValue`	`number`	-	The smallest value allowed for the input.
`maxValue`	`number`	-	The largest value allowed for the input.
`step`	`number`	`1`	The amount the value changes with each increment or decrement.
`formatOptions`	Intl.NumberFormatOptions	-	Formatting options for the value (e.g. currency, percentage).
`isWheelDisabled`	`boolean`	`false`	Disables changing the value with scroll.
`disabled`	`boolean`	`false`	Whether the input is disabled.
`readOnly`	`boolean`	`false`	Whether the input is read only.
`required`	`boolean`	`false`	Whether the input is required.
`invalid`	`boolean`	`false`	Whether the input is shown in an invalid state.
`validate`	`(value: number) => ValidationResult \| true \| null \| undefined`	-	Custom validation function for the number value.
`validationBehavior`	`'aria' \| 'native'`	`'native'`	Whether to use native HTML or ARIA form validation.
`aria-label`	`string`	-	Defines a string that labels the current element.
`aria-labelledby`	`string`	-	Identifies the element (or elements) that label the element.
`aria-describedby`	`string`	-	Identifies the element that describes the object.
`aria-details`	`string`	-	Identifies the element providing extended description.
`onBlur`	`(e: FocusEvent) => void`	-	Handler called when the element loses focus.
`onFocus`	`(e: FocusEvent) => void`	-	Handler called when the element receives focus.
`onFocusChange`	`(isFocused: boolean) => void`	-	Handler called when the element's focus status changes.
`onKeyDown`	`(e: KeyboardEvent) => void`	-	Handler called when a key is pressed.
`onKeyUp`	`(e: KeyboardEvent) => void`	-	Handler called when a key is released.
`className`	`string`	-	Additional CSS classes to apply to the container.

See the React Aria NumberField documentation for more details.

Composition

The Number Field is composed of the root NumberField component plus NumberFieldGroup, Input, and NumberFieldAction for the stepper buttons. It can be combined with shared field components (FieldLabel, FieldDescription, FieldError) for a complete form control.

NumberField                                     — Root container. Manages numeric state, validation, and ARIA context.
├── FieldLabel                                  — Visible label.
├── NumberFieldGroup                            — Groups the input and stepper buttons into a single layout.
│   ├── Input                                   — Editable text input area for direct typing.
│   ├── NumberFieldAction (slot: decrement)     — Decrement button (Minus icon).
│   └── NumberFieldAction (slot: increment)     — Increment button (Plus icon).
└── FieldDescription                            — Helper text.

Use NumberField as the root. It provides the numeric value, validation state, and keyboard context to all children.
Use FieldLabel to label the field. It is automatically linked to the input.
Use NumberFieldGroup to wrap the input and action buttons. It handles the layout context for absolute-positioned buttons.
Use Input for the editable text area. It accepts direct keyboard input and displays the current value.
Use NumberFieldAction with slot="decrement" or slot="increment" to render the stepper buttons. Each button is absolutely positioned within the group.
Use FieldDescription for helper text. It is automatically announced by screen readers.
Use FieldError for validation messages. It is linked via aria-errormessage when invalid is set.

Accessibility

Keyboard Support: Users can increment and decrement the value using the Arrow Up and Arrow Down keys. Tab navigates to the next focusable element.
Screen Readers: The current value is announced when it changes. The increment and decrement buttons are labeled with localized "Increase" and "Decrease" values.
Focus Management: Focus remains on the input field when using stepper buttons, enabling rapid value adjustments without losing keyboard context.

Number Field

CLI

Manual

On this page