Number Input
A field that allows user input of numeric values.
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-partattribute 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.
Story not foundStory not foundStory not foundAdjusting 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.
Story not foundStory not foundStory not foundScrubbing 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.
Story not foundStory not foundStory not foundClamp 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.
Story not foundStory not foundStory not foundUsage within forms
To use the number input within forms, set the name prop.
Story not foundStory not foundStory not foundFormat 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 | Type | Default |
|---|---|---|
allowMouseWheelWhether to allow mouse wheel to change the value | boolean | |
allowOverflowWhether to allow the value overflow the min/max range | boolean | true |
asChildRender as a different element type. | boolean | |
clampValueOnBlurWhether to clamp the value when the input loses focus (blur) | boolean | true |
defaultValueThe 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. | string | |
disabledWhether the number input is disabled. | boolean | |
focusInputOnChangeWhether to focus input when the value changes | boolean | true |
formThe associate form of the input element. | string | |
formatOptionsThe options to pass to the `Intl.NumberFormat` constructor | NumberFormatOptions | |
idThe unique identifier of the machine. | string | |
idsThe ids of the elements in the number input. Useful for composition. | Partial<{
root: string
label: string
input: string
incrementTrigger: string
decrementTrigger: string
scrubber: string
}> | |
inputModeHints 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 | InputMode | "decimal" |
invalidWhether the number input value is invalid. | boolean | |
localeThe current locale. Based on the BCP 47 definition. | string | "en-US" |
maxThe maximum value of the number input | number | |
minThe minimum value of the number input | number | |
nameThe name attribute of the number input. Useful for form submission. | string | |
onFocusChangeFunction invoked when the number input is focused | (details: FocusChangeDetails) => void | |
onValueChangeFunction invoked when the value changes | (details: ValueChangeDetails) => void | |
onValueInvalidFunction invoked when the value overflows or underflows the min/max range | (details: ValueInvalidDetails) => void | |
patternThe pattern used to check the <input> element's value against | string | "[0-9]*(.[0-9]+)?" |
readOnlyWhether the number input is readonly | boolean | |
spinOnPressWhether to spin the value when the increment/decrement button is pressed | boolean | |
stepThe amount to increment or decrement the value by | number | |
translationsSpecifies the localized strings that identifies the accessibility elements and their states | IntlTranslations | |
valueThe value of the input | string |
Control
| Prop | Type | Default |
|---|---|---|
asChildRender as a different element type. | boolean |
DecrementTrigger
| Prop | Type | Default |
|---|---|---|
asChildRender as a different element type. | boolean |
IncrementTrigger
| Prop | Type | Default |
|---|---|---|
asChildRender as a different element type. | boolean |
Input
| Prop | Type | Default |
|---|---|---|
asChildRender as a different element type. | boolean |
Label
| Prop | Type | Default |
|---|---|---|
asChildRender as a different element type. | boolean |
Scrubber
| Prop | Type | Default |
|---|---|---|
asChildRender as a different element type. | boolean |
Previous
MenuNext
Pagination