Number Input

Import

import { NumberInput } from '@cerberus/react'

Usage

The NumberInput component provides a way to create input fields specifically for numeric values. It includes features such as increment and decrement buttons, and can be easily integrated with form libraries.

Loading example...

Scrubber

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

Loading example...

Sizes

The NumberInput component supports different sizes to accommodate various design requirements. You can specify the size using the size prop.

Loading example...

Custom

You can customize the NumberInput component using the primitive components or style props.

Loading example...

Primitives

You can utilize the primitive components or the css prop to customize the number input.

Component	Description
`NumberInputRoot`	The context provider for the NumberInput parts
`NumberInputLabel`	The label of the NumberInput
`NumberInputControl`	The wrapper of the NumberInput contents
`NumberInputInput`	The input of the NumberInput
`NumberInputIncrementTrigger`	The increment button of the NumberInput
`NumberInputDecrementTrigger`	The decrement button of the NumberInput
`NumberInputScrubber`	The scrubber of the NumberInput

Parts

The NumberInputParts API is an Object containing the full family of components.

Note

It is best to only use the NumberInputParts if you are building a custom solution. Importing Object based components will ship every property it includes into your bundle, regardless if you use it or not.

Name	Description
`Root`	The `NumberInputRoot` component which is the Provider for the family.
`Label`	The `NumberInputLabel` component which displays the label and "required" notice.
`Input`	The `NumberInputInput` component which is the input field.
`Control`	The `NumberInputControl` component which is the wrapper for the input and buttons.
`IncrementTrigger`	The `NumberInputIncrementTrigger` component which is the increment button.
`DecrementTrigger`	The `NumberInputDecrementTrigger` component which is the decrement button.
`Scrubber`	The `NumberInputScrubber` component which is the scrubber control.

API

Props

Root

Props

Prop	Type	Required	Default	Description
`allowMouseWheel`	`boolean`	false	`undefined`	Whether to allow mouse wheel to change the value
`allowOverflow`	`boolean`	false	`true`	Whether to allow the value overflow the min/max range
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.
`clampValueOnBlur`	`boolean`	false	`true`	Whether to clamp the value when the input loses focus (blur)
`defaultValue`	`string`	false	`undefined`	The initial value of the input when rendered. Use when you don't need to control the value of the input.
`disabled`	`boolean`	false	`undefined`	Whether the number input is disabled.
`focusInputOnChange`	`boolean`	false	`true`	Whether to focus input when the value changes
`form`	`string`	false	`undefined`	The associate form of the input element.
`formatOptions`	`NumberFormatOptions`	false	`undefined`	The options to pass to the `Intl.NumberFormat` constructor
`id`	`string`	false	`undefined`	The unique identifier of the machine.
`ids`	`Partial<{ root: string, label: string, input: string, incrementTrigger: string, decrementTrigger: string, scrubber: string }>`	false	`undefined`	The ids of the elements in the number input. Useful for composition.
`inputMode`	`InputMode`	false	`"decimal"`	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`	false	`undefined`	Whether the number input value is invalid.
`largeStep`	`number`	false	`10 * step`	The amount to increment or decrement the value by when the `Shift` key is held.
`locale`	`string`	false	`"en-US"`	The current locale. Based on the BCP 47 definition.
`max`	`number`	false	`Number.MAX_SAFE_INTEGER`	The maximum value of the number input
`min`	`number`	false	`Number.MIN_SAFE_INTEGER`	The minimum value of the number input
`name`	`string`	false	`undefined`	The name attribute of the number input. Useful for form submission.
`onFocusChange`	`(details: FocusChangeDetails) => void`	false	`undefined`	Function invoked when the number input is focused
`onValueChange`	`(details: ValueChangeDetails) => void`	false	`undefined`	Function invoked when the value changes
`onValueCommit`	`(details: ValueChangeDetails) => void`	false	`undefined`	Function invoked when the value is committed (when the input is blurred or the Enter key is pressed)
`onValueInvalid`	`(details: ValueInvalidDetails) => void`	false	`undefined`	Function invoked when the value overflows or underflows the min/max range
`pattern`	`string`	false	`"-?[0-9]*(.[0-9]+)?"`	The pattern used to check the `<input>` element's value against
`readOnly`	`boolean`	false	`undefined`	Whether the number input is readonly
`required`	`boolean`	false	`undefined`	Whether the number input is required
`smallStep`	`number`	false	`step / 10`	The amount to increment or decrement the value by when the `Alt` key is held.
`spinOnPress`	`boolean`	false	`true`	Whether to spin the value when the increment/decrement button is pressed
`step`	`number`	false	`1`	The amount to increment or decrement the value by
`translations`	`IntlTranslations`	false	`undefined`	Specifies the localized strings that identifies the accessibility elements and their states
`value`	`string`	false	`undefined`	The controlled value of the input

Data Attributes

Attribute	Description / Value
`data-scope`	number-input
`data-part`	root
`data-disabled`	Present when disabled
`data-focus`	Present when focused
`data-invalid`	Present when invalid
`data-scrubbing`

Control

Props

Prop	Type	Required	Default	Description
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.

Data Attributes

Attribute	Description / Value
`data-scope`	number-input
`data-part`	control
`data-focus`	Present when focused
`data-disabled`	Present when disabled
`data-invalid`	Present when invalid
`data-scrubbing`

DecrementTrigger

Props

Prop	Type	Required	Default	Description
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.

Data Attributes

Attribute	Description / Value
`data-scope`	number-input
`data-part`	decrement-trigger
`data-disabled`	Present when disabled
`data-scrubbing`

IncrementTrigger

Props

Prop	Type	Required	Default	Description
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.

Data Attributes

Attribute	Description / Value
`data-scope`	number-input
`data-part`	increment-trigger
`data-disabled`	Present when disabled
`data-scrubbing`

Input

Props

Prop	Type	Required	Default	Description
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.

Data Attributes

Attribute	Description / Value
`data-scope`	number-input
`data-part`	input
`data-invalid`	Present when invalid
`data-disabled`	Present when disabled
`data-scrubbing`

Label

Props

Prop	Type	Required	Default	Description
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.

Data Attributes

Attribute	Description / Value
`data-scope`	number-input
`data-part`	label
`data-disabled`	Present when disabled
`data-focus`	Present when focused
`data-invalid`	Present when invalid
`data-required`	Present when required
`data-scrubbing`

RootProvider

Props

Prop	Type	Required	Default	Description
`value`	`UseNumberInputReturn`	true	`undefined`	undefined
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.

Scrubber

Props

Prop	Type	Required	Default	Description
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.

Data Attributes

Attribute	Description / Value
`data-scope`	number-input
`data-part`	scrubber
`data-disabled`	Present when disabled
`data-scrubbing`

ValueText

Props

Prop	Type	Required	Default	Description
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.

Data Attributes

Attribute	Description / Value
`data-scope`	number-input
`data-part`	value-text
`data-disabled`	Present when disabled
`data-invalid`	Present when invalid
`data-focus`	Present when focused
`data-scrubbing`

Context

API:

Property	Type	Description
`focused`	`boolean`	Whether the input is focused.
`invalid`	`boolean`	Whether the input is invalid.
`empty`	`boolean`	Whether the input value is empty.
`value`	`string`	The formatted value of the input.
`valueAsNumber`	`number`	The value of the input as a number.
`setValue`	`(value: number) => void`	Function to set the value of the input.
`clearValue`	`VoidFunction`	Function to clear the value of the input.
`increment`	`VoidFunction`	Function to increment the value of the input by the step.
`decrement`	`VoidFunction`	Function to decrement the value of the input by the step.
`setToMax`	`VoidFunction`	Function to set the value of the input to the max.
`setToMin`	`VoidFunction`	Function to set the value of the input to the min.
`focus`	`VoidFunction`	Function to focus the input.

Accessibility

Complies with the Spinbutton WAI-ARIA design pattern.

Keyboard Support

Key	Description
`ArrowUp`	Increments the value of the number input by a predefined step.
`ArrowDown`	Decrements the value of the number input by a predefined step.
`Shift + ArrowUp`	Increments the value of the number input by the `largeStep` amount.
`Shift + ArrowDown`	Decrements the value of the number input by the `largeStep` amount.
`Alt + ArrowUp`	Increments the value of the number input by the `smallStep` amount.
`Alt + ArrowDown`	Decrements the value of the number input by the `smallStep` amount.
`Home`	Sets the value of the number input to its minimum allowed value.
`End`	Sets the value of the number input to its maximum allowed value.
`Enter`	Submits the value entered in the number input.

Import

import { NumberInput } from '@cerberus/react'

Usage

How many?

Choose your quantity.

Loading example...

Scrubber

How many?

Use your mouse wheel to change the value.

Loading example...

Sizes

The NumberInput component supports different sizes to accommodate various design requirements. You can specify the size using the size prop.

Size sm

Size md

Size lg

Loading example...

Custom

You can customize the NumberInput component using the primitive components or style props.

This is custom

Loading example...

Primitives

You can utilize the primitive components or the css prop to customize the number input.

Component	Description
`NumberInputRoot`	The context provider for the NumberInput parts
`NumberInputLabel`	The label of the NumberInput
`NumberInputControl`	The wrapper of the NumberInput contents
`NumberInputInput`	The input of the NumberInput
`NumberInputIncrementTrigger`	The increment button of the NumberInput
`NumberInputDecrementTrigger`	The decrement button of the NumberInput
`NumberInputScrubber`	The scrubber of the NumberInput

Parts

The NumberInputParts API is an Object containing the full family of components.

Note

Name	Description
`Root`	The `NumberInputRoot` component which is the Provider for the family.
`Label`	The `NumberInputLabel` component which displays the label and "required" notice.
`Input`	The `NumberInputInput` component which is the input field.
`Control`	The `NumberInputControl` component which is the wrapper for the input and buttons.
`IncrementTrigger`	The `NumberInputIncrementTrigger` component which is the increment button.
`DecrementTrigger`	The `NumberInputDecrementTrigger` component which is the decrement button.
`Scrubber`	The `NumberInputScrubber` component which is the scrubber control.

API

Props

Root

Props

Prop	Type	Required	Default	Description
`allowMouseWheel`	`boolean`	false	`undefined`	Whether to allow mouse wheel to change the value
`allowOverflow`	`boolean`	false	`true`	Whether to allow the value overflow the min/max range
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.
`clampValueOnBlur`	`boolean`	false	`true`	Whether to clamp the value when the input loses focus (blur)
`defaultValue`	`string`	false	`undefined`	The initial value of the input when rendered. Use when you don't need to control the value of the input.
`disabled`	`boolean`	false	`undefined`	Whether the number input is disabled.
`focusInputOnChange`	`boolean`	false	`true`	Whether to focus input when the value changes
`form`	`string`	false	`undefined`	The associate form of the input element.
`formatOptions`	`NumberFormatOptions`	false	`undefined`	The options to pass to the `Intl.NumberFormat` constructor
`id`	`string`	false	`undefined`	The unique identifier of the machine.
`ids`	`Partial<{ root: string, label: string, input: string, incrementTrigger: string, decrementTrigger: string, scrubber: string }>`	false	`undefined`	The ids of the elements in the number input. Useful for composition.
`inputMode`	`InputMode`	false	`"decimal"`	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`	false	`undefined`	Whether the number input value is invalid.
`largeStep`	`number`	false	`10 * step`	The amount to increment or decrement the value by when the `Shift` key is held.
`locale`	`string`	false	`"en-US"`	The current locale. Based on the BCP 47 definition.
`max`	`number`	false	`Number.MAX_SAFE_INTEGER`	The maximum value of the number input
`min`	`number`	false	`Number.MIN_SAFE_INTEGER`	The minimum value of the number input
`name`	`string`	false	`undefined`	The name attribute of the number input. Useful for form submission.
`onFocusChange`	`(details: FocusChangeDetails) => void`	false	`undefined`	Function invoked when the number input is focused
`onValueChange`	`(details: ValueChangeDetails) => void`	false	`undefined`	Function invoked when the value changes
`onValueCommit`	`(details: ValueChangeDetails) => void`	false	`undefined`	Function invoked when the value is committed (when the input is blurred or the Enter key is pressed)
`onValueInvalid`	`(details: ValueInvalidDetails) => void`	false	`undefined`	Function invoked when the value overflows or underflows the min/max range
`pattern`	`string`	false	`"-?[0-9]*(.[0-9]+)?"`	The pattern used to check the `<input>` element's value against
`readOnly`	`boolean`	false	`undefined`	Whether the number input is readonly
`required`	`boolean`	false	`undefined`	Whether the number input is required
`smallStep`	`number`	false	`step / 10`	The amount to increment or decrement the value by when the `Alt` key is held.
`spinOnPress`	`boolean`	false	`true`	Whether to spin the value when the increment/decrement button is pressed
`step`	`number`	false	`1`	The amount to increment or decrement the value by
`translations`	`IntlTranslations`	false	`undefined`	Specifies the localized strings that identifies the accessibility elements and their states
`value`	`string`	false	`undefined`	The controlled value of the input

Data Attributes

Attribute	Description / Value
`data-scope`	number-input
`data-part`	root
`data-disabled`	Present when disabled
`data-focus`	Present when focused
`data-invalid`	Present when invalid
`data-scrubbing`

Control

Props

Prop	Type	Required	Default	Description
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.

Data Attributes

Attribute	Description / Value
`data-scope`	number-input
`data-part`	control
`data-focus`	Present when focused
`data-disabled`	Present when disabled
`data-invalid`	Present when invalid
`data-scrubbing`

DecrementTrigger

Props

Prop	Type	Required	Default	Description
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.

Data Attributes

Attribute	Description / Value
`data-scope`	number-input
`data-part`	decrement-trigger
`data-disabled`	Present when disabled
`data-scrubbing`

IncrementTrigger

Props

Prop	Type	Required	Default	Description
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.

Data Attributes

Attribute	Description / Value
`data-scope`	number-input
`data-part`	increment-trigger
`data-disabled`	Present when disabled
`data-scrubbing`

Input

Props

Prop	Type	Required	Default	Description
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.

Data Attributes

Attribute	Description / Value
`data-scope`	number-input
`data-part`	input
`data-invalid`	Present when invalid
`data-disabled`	Present when disabled
`data-scrubbing`

Label

Props

Prop	Type	Required	Default	Description
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.

Data Attributes

Attribute	Description / Value
`data-scope`	number-input
`data-part`	label
`data-disabled`	Present when disabled
`data-focus`	Present when focused
`data-invalid`	Present when invalid
`data-required`	Present when required
`data-scrubbing`

RootProvider

Props

Prop	Type	Required	Default	Description
`value`	`UseNumberInputReturn`	true	`undefined`	undefined
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.

Scrubber

Props

Prop	Type	Required	Default	Description
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.

Data Attributes

Attribute	Description / Value
`data-scope`	number-input
`data-part`	scrubber
`data-disabled`	Present when disabled
`data-scrubbing`

ValueText

Props

Prop	Type	Required	Default	Description
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.

Data Attributes

Attribute	Description / Value
`data-scope`	number-input
`data-part`	value-text
`data-disabled`	Present when disabled
`data-invalid`	Present when invalid
`data-focus`	Present when focused
`data-scrubbing`

Context

API:

Property	Type	Description
`focused`	`boolean`	Whether the input is focused.
`invalid`	`boolean`	Whether the input is invalid.
`empty`	`boolean`	Whether the input value is empty.
`value`	`string`	The formatted value of the input.
`valueAsNumber`	`number`	The value of the input as a number.
`setValue`	`(value: number) => void`	Function to set the value of the input.
`clearValue`	`VoidFunction`	Function to clear the value of the input.
`increment`	`VoidFunction`	Function to increment the value of the input by the step.
`decrement`	`VoidFunction`	Function to decrement the value of the input by the step.
`setToMax`	`VoidFunction`	Function to set the value of the input to the max.
`setToMin`	`VoidFunction`	Function to set the value of the input to the min.
`focus`	`VoidFunction`	Function to focus the input.

Accessibility

Complies with the Spinbutton WAI-ARIA design pattern.

Keyboard Support

Key	Description
`ArrowUp`	Increments the value of the number input by a predefined step.
`ArrowDown`	Decrements the value of the number input by a predefined step.
`Shift + ArrowUp`	Increments the value of the number input by the `largeStep` amount.
`Shift + ArrowDown`	Decrements the value of the number input by the `largeStep` amount.
`Alt + ArrowUp`	Increments the value of the number input by the `smallStep` amount.
`Alt + ArrowDown`	Decrements the value of the number input by the `smallStep` amount.
`Home`	Sets the value of the number input to its minimum allowed value.
`End`	Sets the value of the number input to its maximum allowed value.
`Enter`	Submits the value entered in the number input.