Number Input

Used to enter a number, and increment or decrement the value using stepper buttons.

import { NumberInputField, NumberInputRoot } from "@/components/ui/number-input"

const Demo = () => {
  return (
    <NumberInputRoot defaultValue="10" width="200px">
      <NumberInputField />
    </NumberInputRoot>
  )
}

Setup

If you don't already have the snippet, run the following command to add the number-input snippet

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

The snippet includes a closed component composition for the NumberInput component.

Usage

import {
  NumberInputField,
  NumberInputLabel,
  NumberInputRoot,
} from "@/components/ui/number-input"

<NumberInputRoot>
  <NumberInputLabel />
  <NumberInputField />
</NumberInputRoot>

Examples

Sizes

Use the size prop to change the size of the number input.

import { For, Stack } from "@chakra-ui/react"
import { NumberInputField, NumberInputRoot } from "@/components/ui/number-input"

const Demo = () => {
  return (
    <Stack gap="5" width="200px">
      <For each={["xs", "sm", "md", "lg"]}>
        {(size) => (
          <NumberInputRoot size={size} key={size} defaultValue="10">
            <NumberInputField />
          </NumberInputRoot>
        )}
      </For>
    </Stack>
  )
}

Formatting

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

import { Stack } from "@chakra-ui/react"
import { NumberInputField, NumberInputRoot } from "@/components/ui/number-input"

const Demo = () => {
  return (
    <Stack gap="5" maxW="200px">
      <NumberInputRoot
        defaultValue="5"
        step={0.01}
        formatOptions={{
          style: "percent",
        }}
      >
        <NumberInputField />
      </NumberInputRoot>

      <NumberInputRoot
        defaultValue="45"
        formatOptions={{
          style: "currency",
          currency: "EUR",
          currencyDisplay: "code",
          currencySign: "accounting",
        }}
      >
        <NumberInputField />
      </NumberInputRoot>

      <NumberInputRoot
        defaultValue="4"
        formatOptions={{
          style: "unit",
          unit: "inch",
          unitDisplay: "long",
        }}
      >
        <NumberInputField />
      </NumberInputRoot>
    </Stack>
  )
}

Min and Max

Use the min and max props 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.

import { NumberInputField, NumberInputRoot } from "@/components/ui/number-input"

const Demo = () => {
  return (
    <NumberInputRoot width="200px" defaultValue="10" min={5} max={50}>
      <NumberInputField />
    </NumberInputRoot>
  )
}

Step

Use the step prop to change the increment or decrement interval of the number input.

import { NumberInputField, NumberInputRoot } from "@/components/ui/number-input"

const Demo = () => {
  return (
    <NumberInputRoot maxW="200px" defaultValue="2" step={3}>
      <NumberInputField />
    </NumberInputRoot>
  )
}

Controlled

Use the value and onValueChange props to control the value of the number input.

"use client"

import { NumberInputField, NumberInputRoot } from "@/components/ui/number-input"
import { useState } from "react"

const Demo = () => {
  const [value, setValue] = useState("10")
  return (
    <NumberInputRoot
      maxW="200px"
      value={value}
      onValueChange={(e) => setValue(e.value)}
    >
      <NumberInputField />
    </NumberInputRoot>
  )
}

Mobile Stepper

Use the StepperInput component to create a stepper input for mobile devices.

You can also apply spinOnPress: false to disable the spin functionality.

import { StepperInput } from "@/components/ui/stepper-input"

const Demo = () => {
  return <StepperInput defaultValue="3" />
}

Mouse Wheel

Use the allowMouseWheel prop to enable or disable the mouse wheel to change

import { NumberInputField, NumberInputRoot } from "@/components/ui/number-input"

const Demo = () => {
  return (
    <NumberInputRoot defaultValue="10" width="200px" allowMouseWheel>
      <NumberInputField />
    </NumberInputRoot>
  )
}

Disabled

Use the disabled prop to disable the number input.

import { NumberInputField, NumberInputRoot } from "@/components/ui/number-input"

const Demo = () => {
  return (
    <NumberInputRoot defaultValue="10" width="200px" disabled>
      <NumberInputField />
    </NumberInputRoot>
  )
}

Invalid

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

Enter Number

The entry is invalid

import { Field } from "@/components/ui/field"
import { NumberInputField, NumberInputRoot } from "@/components/ui/number-input"

const Demo = () => {
  return (
    <Field label="Enter Number" invalid errorText="The entry is invalid">
      <NumberInputRoot defaultValue="10" width="200px">
        <NumberInputField />
      </NumberInputRoot>
    </Field>
  )
}

Helper Text

Use the Field component and pass the helperText prop to add helper text to the number input.

Enter Number

Enter a number between 1 and 10

import { Field } from "@/components/ui/field"
import { NumberInputField, NumberInputRoot } from "@/components/ui/number-input"

const Demo = () => {
  return (
    <Field label="Enter Number" helperText="Enter a number between 1 and 10">
      <NumberInputRoot width="200px">
        <NumberInputField />
      </NumberInputRoot>
    </Field>
  )
}

Hook Form

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

"use client"

import { Button } from "@chakra-ui/react"
import { zodResolver } from "@hookform/resolvers/zod"
import { Field } from "@/components/ui/field"
import { NumberInputField, NumberInputRoot } from "@/components/ui/number-input"
import { Controller, useForm } from "react-hook-form"
import { z } from "zod"

const formSchema = z.object({
  number: z.string({ message: "Number is required" }),
})

type FormValues = z.infer<typeof formSchema>

const Demo = () => {
  const {
    control,
    handleSubmit,
    formState: { errors },
  } = useForm<FormValues>({
    resolver: zodResolver(formSchema),
  })

  const onSubmit = handleSubmit((data) => console.log(data))

  return (
    <form onSubmit={onSubmit}>
      <Field
        label="Number"
        invalid={!!errors.number}
        errorText={errors.number?.message}
      >
        <Controller
          name="number"
          control={control}
          render={({ field }) => (
            <NumberInputRoot
              disabled={field.disabled}
              name={field.name}
              value={field.value}
              onValueChange={({ value }) => {
                field.onChange(value)
              }}
            >
              <NumberInputField onBlur={field.onBlur} />
            </NumberInputRoot>
          )}
        />
      </Field>

      <Button size="sm" type="submit" mt="4">
        Submit
      </Button>
    </form>
  )
}

Props

Root

Prop	Default	Type
`allowOverflow`	`true`	`boolean` Whether to allow the value overflow the min/max range
`clampValueOnBlur`	`true`	`boolean` Whether to clamp the value when the input loses focus (blur)
`focusInputOnChange`	`true`	`boolean` Whether to focus input when the value changes
`inputMode`	`'\'decimal\''`	`InputMode` Hints at the type of data that might be entered by the user. It also determines the type of keyboard shown to the user on mobile devices
`locale`	`'\'en-US\''`	`string` The current locale. Based on the BCP 47 definition.
`max`	`'Number.MAX_SAFE_INTEGER'`	`number` The maximum value of the number input
`min`	`'Number.MIN_SAFE_INTEGER'`	`number` The minimum value of the number input
`pattern`	`'\'[0-9]*(.[0-9]+)?\''`	`string` The pattern used to check the <input> element's value against
`spinOnPress`	`true`	`boolean` Whether to spin the value when the increment/decrement button is pressed
`step`	`'1'`	`number` The amount to increment or decrement the value by
`colorPalette`	`'gray'`	`'gray' \| 'red' \| 'orange' \| 'yellow' \| 'green' \| 'teal' \| 'blue' \| 'cyan' \| 'purple' \| 'pink' \| 'accent'` The color palette of the component
`size`	`'md'`	`'xs' \| 'sm' \| 'md' \| 'lg'` The size of the component
`variant`	`'outline'`	`'outline' \| 'filled' \| 'flushed'` The variant of the component
`allowMouseWheel`		`boolean` Whether to allow mouse wheel to change the value
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`defaultValue`		`string` The initial value of the number input when it is first rendered. Use when you do not need to control the state of the number input.
`disabled`		`boolean` Whether the number input is disabled.
`form`		`string` The associate form of the input element.
`formatOptions`		`NumberFormatOptions` The options to pass to the `Intl.NumberFormat` constructor
`id`		`string` The unique identifier of the machine.
`ids`		`Partial<{ root: string label: string input: string incrementTrigger: string decrementTrigger: string scrubber: string }>` The ids of the elements in the number input. Useful for composition.
`invalid`		`boolean` Whether the number input value is invalid.
`name`		`string` The name attribute of the number input. Useful for form submission.
`onFocusChange`		`(details: FocusChangeDetails) => void` Function invoked when the number input is focused
`onValueChange`		`(details: ValueChangeDetails) => void` Function invoked when the value changes
`onValueInvalid`		`(details: ValueInvalidDetails) => void` Function invoked when the value overflows or underflows the min/max range
`readOnly`		`boolean` Whether the number input is readonly
`required`		`boolean` Whether the number input is required
`translations`		`IntlTranslations` Specifies the localized strings that identifies the accessibility elements and their states
`value`		`string` The value of the input

Pagination

Number Input

.css-vfo6uh{color:var(--chakra-colors-fg);-webkit-text-decoration:underline;text-decoration:underline;text-underline-offset:3px;text-decoration-thickness:2px;text-decoration-color:var(--chakra-colors-border-emphasized);font-weight:500;}Setup

Setup