Number Input

A field that allows user input of numeric values.

Label

Anatomy

To set up the number input correctly, you'll need to understand its anatomy and how we name its parts.

Each part includes a data-part attribute to help identify them in the DOM.

Examples

Learn how to use the NumberInput component in your project. Let's take a look at the most basic example:

import { NumberInput } from '@ark-ui/react'

export const Basic = () => (
  <NumberInput.Root>
    <NumberInput.Label>Label</NumberInput.Label>
    <NumberInput.Input />
    <NumberInput.Control>
      <NumberInput.DecrementTrigger>-1</NumberInput.DecrementTrigger>
      <NumberInput.IncrementTrigger>+1</NumberInput.IncrementTrigger>
    </NumberInput.Control>
  </NumberInput.Root>
)

import { NumberInput } from '@ark-ui/solid'

export const Basic = () => (
  <NumberInput.Root>
    <NumberInput.Label>Label</NumberInput.Label>
    <NumberInput.Input />
    <NumberInput.Control>
      <NumberInput.DecrementTrigger>-1</NumberInput.DecrementTrigger>
      <NumberInput.IncrementTrigger>+1</NumberInput.IncrementTrigger>
    </NumberInput.Control>
  </NumberInput.Root>
)

<script setup lang="ts">
import { NumberInput } from '@ark-ui/vue'
</script>

<template>
  <NumberInput.Root>
    <NumberInput.Label>Label</NumberInput.Label>
    <NumberInput.Input />
    <NumberInput.Control>
      <NumberInput.DecrementTrigger>-1</NumberInput.DecrementTrigger>
      <NumberInput.IncrementTrigger>+1</NumberInput.IncrementTrigger>
    </NumberInput.Control>
  </NumberInput.Root>
</template>

Setting a minimum and maximum value

Pass the min prop or max prop to set an upper and lower limit for the input. By default, the input will restrict the value to stay within the specified range.

Example not found

Example not found

Example not found

Adjusting the precision of the value

In some cases, you might need the value to be rounded to specific decimal points. Set the formatOptions and provide Intl.NumberFormatOptions such as maximumFractionDigits or minimumFractionDigits.

Example not found

Example not found

Example not found

Scrubbing the input value

The NumberInput supports the scrubber interaction pattern. To use this pattern, render the NumberInput.Scrubber component. It uses the Pointer lock API and tracks the pointer movement. It also renders a virtual cursor which mimics the real cursor's pointer.

import { NumberInput } from '@ark-ui/react'

export const Scrubber = () => (
  <NumberInput.Root>
    <NumberInput.Scrubber />
    <NumberInput.Label>Label</NumberInput.Label>
    <NumberInput.Input />
    <NumberInput.Control>
      <NumberInput.DecrementTrigger>-1</NumberInput.DecrementTrigger>
      <NumberInput.IncrementTrigger>+1</NumberInput.IncrementTrigger>
    </NumberInput.Control>
  </NumberInput.Root>
)

import { NumberInput } from '@ark-ui/solid'

export const Scrubber = () => (
  <NumberInput.Root>
    <NumberInput.Scrubber />
    <NumberInput.Label>Label</NumberInput.Label>
    <NumberInput.Input />
    <NumberInput.Control>
      <NumberInput.DecrementTrigger>-1</NumberInput.DecrementTrigger>
      <NumberInput.IncrementTrigger>+1</NumberInput.IncrementTrigger>
    </NumberInput.Control>
  </NumberInput.Root>
)

<script setup lang="ts">
import { NumberInput } from '@ark-ui/vue'
</script>

<template>
  <NumberInput.Root>
    <NumberInput.Scrubber />
    <NumberInput.Label>Label</NumberInput.Label>
    <NumberInput.Input />
    <NumberInput.Control>
      <NumberInput.DecrementTrigger>-1</NumberInput.DecrementTrigger>
      <NumberInput.IncrementTrigger>+1</NumberInput.IncrementTrigger>
    </NumberInput.Control>
  </NumberInput.Root>
</template>

Using the mouse wheel to change value

The NumberInput exposes a way to increment/decrement the value using the mouse wheel event. To activate this, set the allowMouseWheel prop to true.

Example not found

Example not found

Example not found

Clamp value when user blurs the input

In most cases, users can type custom values in the input field. If the typed value is greater than the max, the value is reset to max when the user blur out of the input.

To disable this behavior, pass clampValueOnBlur and set to false.

Example not found

Example not found

Example not found

Usage within forms

To use the number input within forms, set the name prop.

Example not found

Example not found

Example not found

Format and parse value

To apply custom formatting to the input's value, set the formatOptions and provide Intl.NumberFormatOptions such as style and currency.

import { NumberInput } from '@ark-ui/react'

export const Formatted = () => (
  <NumberInput.Root
    formatOptions={{
      style: 'currency',
      currency: 'USD',
    }}
  >
    <NumberInput.Scrubber />
    <NumberInput.Label>Label</NumberInput.Label>
    <NumberInput.Input />
    <NumberInput.Control>
      <NumberInput.DecrementTrigger>-1</NumberInput.DecrementTrigger>
      <NumberInput.IncrementTrigger>+1</NumberInput.IncrementTrigger>
    </NumberInput.Control>
  </NumberInput.Root>
)

import { NumberInput } from '@ark-ui/solid'

export const Formatted = () => (
  <NumberInput.Root
    formatOptions={{
      style: 'currency',
      currency: 'USD',
    }}
  >
    <NumberInput.Scrubber />
    <NumberInput.Label>Label</NumberInput.Label>
    <NumberInput.Input />
    <NumberInput.Control>
      <NumberInput.DecrementTrigger>-1</NumberInput.DecrementTrigger>
      <NumberInput.IncrementTrigger>+1</NumberInput.IncrementTrigger>
    </NumberInput.Control>
  </NumberInput.Root>
)

<script setup lang="ts">
import { NumberInput } from '@ark-ui/vue'
</script>

<template>
  <NumberInput.Root :formatOptions="{ style: 'currency', currency: 'USD' }">
    <NumberInput.Scrubber />
    <NumberInput.Label>Label</NumberInput.Label>
    <NumberInput.Input />
    <NumberInput.Control>
      <NumberInput.DecrementTrigger>-1</NumberInput.DecrementTrigger>
      <NumberInput.IncrementTrigger>+1</NumberInput.IncrementTrigger>
    </NumberInput.Control>
  </NumberInput.Root>
</template>

API Reference

Root

Prop	Default	Type
`allowMouseWheel`		`boolean` Whether to allow mouse wheel to change the value
`allowOverflow`	`true`	`boolean` Whether to allow the value overflow the min/max range
`asChild`		`boolean` Render as a different element type.
`clampValueOnBlur`	`true`	`boolean` Whether to clamp the value when the input loses focus (blur)
`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.
`focusInputOnChange`	`true`	`boolean` Whether to focus input when the value changes
`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.
`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
`invalid`		`boolean` Whether the number input value is invalid.
`locale`	`'en-US'`	`string` The current locale. Based on the BCP 47 definition.
`max`		`number` The maximum value of the number input
`min`		`number` The minimum value of the number input
`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
`pattern`	`'[0-9]*(.[0-9]+)?'`	`string` The pattern used to check the <input> element's value against
`readOnly`		`boolean` Whether the number input is readonly
`spinOnPress`		`boolean` Whether to spin the value when the increment/decrement button is pressed
`step`		`number` The amount to increment or decrement the value by
`translations`		`IntlTranslations` Specifies the localized strings that identifies the accessibility elements and their states
`value`		`string` The value of the input

Control

Prop	Default	Type
`asChild`		`boolean` Render as a different element type.

DecrementTrigger

Prop	Default	Type
`asChild`		`boolean` Render as a different element type.

IncrementTrigger

Prop	Default	Type
`asChild`		`boolean` Render as a different element type.

Input

Prop	Default	Type
`asChild`		`boolean` Render as a different element type.

Label

Prop	Default	Type
`asChild`		`boolean` Render as a different element type.

Scrubber

Prop	Default	Type
`asChild`		`boolean` Render as a different element type.