Number Input

Usage

import { NumberInput } from "@chakra-ui/react"

<NumberInput.Root>
  <NumberInput.Label />
  <NumberInput.ValueText />
  <NumberInput.Control>
    <NumberInput.IncrementTrigger />
    <NumberInput.DecrementTrigger />
  </NumberInput.Control>
  <NumberInput.Scrubber />
  <NumberInput.Input />
</NumberInput.Root>

:::info

If you prefer a closed component composition, check out the snippet below.

:::

Shortcuts

The NumberInput component provides a set of shortcuts for common use cases

NumberInputControl

This component renders the NumberInput.IncrementTrigger and NumberInput.DecrementTrigger within it by default.

Writing this:

<NumberInput.Control />

is shorthand for writing this if you don't need to customize the triggers:

<NumberInput.Control>
  <NumberInput.IncrementTrigger />
  <NumberInput.DecrementTrigger />
</NumberInput.Control>

Examples

Sizes

Pass the size prop to the NumberInput.Root component to change the size of the number input.

Formatting

Pass the formatOptions prop to the NumberInput.Root component to format the number input value. The value of this maps to Intl.NumberFormatOptions and is applied based on the current locale.

Min and Max

Pass the min and max props to the NumberInput.Root component to set the minimum and maximum values of the number input.

If value entered is less than min or greater than max, the value will be clamped to the nearest boundary on blur, or enter key press.

Step

Pass the step prop to the NumberInput.Root component to change the increment or decrement interval of the number input.

Controlled

Pass the value and onValueChange props to the NumberInput.Root component to control the value of the number input.

Mobile Stepper

Here's an example of how to compose the number input as a mobile stepper.

Mouse Wheel

Pass the allowMouseWheel prop to the NumberInput.Root component to enable or disable the mouse wheel to change

Disabled

Pass the disabled prop to the NumberInput.Root component to disable the number input.

Invalid

Use the Field component and the invalid prop to indicate that the number input is invalid.

Helper Text

Compose the Field and Field.HelperText components to add helper text to the number input.

Element

Here's an example of how to compose the number input with the input group component to add an element on either the left or right.

Scrubber

Use the NumberInput.Scrubber component to make the number input supports scrubber interactions.

Hook Form

Here is an example of how to use the NumberInput component with react-hook-form.

Closed Component

Here's how to setup the Number Input for a closed component composition.

If you want to automatically add the closed component to your project, run the command:

npx @chakra-ui/cli snippet add number-input

Here's how to use the it

<NumberInputRoot>
  <NumberInputField />
</NumberInputRoot>

Guides

Why use string values?

When controlling the NumberInput component, use string values instead of converting to numbers. This preserves locale-specific formatting, especially for currencies with different decimal and thousands separators (e.g., 1.523,30 vs 1,523.30).

const [value, setValue] = useState("0")

<NumberInput.Root
  value={value}
  onValueChange={(details) => setValue(details.value)}
>
</NumberInput.Root>

If you need a numeric value for form submission, use NumberInput.Context to access valueAsNumber:

<NumberInput.Root
  value={value}
  onValueChange={(details) => setValue(details.value)}
>
  <NumberInput.Input />
  <NumberInput.Context>
    {(context) => (
      <input type="hidden" name="amount" value={context.valueAsNumber} />
    )}
  </NumberInput.Context>
</NumberInput.Root>

Props

Root

Explorer

Explore the NumberInput component parts interactively. Click on parts in the sidebar to highlight them in the preview.