Number Input

The number input component provides a structured way for users to input numerical data with built-in validation and controls. It combines a text input field with stepper buttons and can include unit selection functionality for measurements, currency, or other quantifiable values.

import {NumberInput} from "@qualcomm-ui/react/number-input"

Examples

Simple

The simple API bundles all subcomponents together into a single component.

Label

<NumberInput className="w-72" label="Label" placeholder="Enter a number" />

Composite

The composite pattern provides full control over the component's elements by composing individual subcomponents.

Label

Optional hint

<NumberInput.Root className="w-72">
  <NumberInput.Label>Label</NumberInput.Label>
  <NumberInput.InputGroup>
    <NumberInput.Input placeholder="Enter a number" />
    <NumberInput.Control />
    <NumberInput.ErrorIndicator />
  </NumberInput.InputGroup>
  <NumberInput.Hint>Optional hint</NumberInput.Hint>
</NumberInput.Root>

Min and Max values

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

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

<NumberInput
  aria-label="input min-max demo"
  className="w-72"
  defaultValue="5"
  max={10}
  min={5}
/>

Step interval

Pass the step prop to the root component to set the increment or decrement step interval.

<NumberInput
  aria-label="Steps demo"
  className="w-72"
  placeholder="Enter a number"
  step={3}
/>

States

The following shows how the NumberInput component appears in each interactive state.

Disabled

Read only

Required

Invalid

<NumberInput disabled label="Disabled" placeholder="Disabled" />
<NumberInput label="Read only" placeholder="Read only" readOnly />
<NumberInput label="Required" placeholder="Required" required />
<NumberInput
  errorText="Invalid"
  invalid
  label="Invalid"
  placeholder="Invalid"
/>

Controlled Value

Use the value, onValueChange and defaultValue props to control the value of the input field. These props follow our controlled state pattern.

Controlled Value

import {type ReactElement, useState} from "react"

import {NumberInput} from "@qualcomm-ui/react/number-input"

export function NumberInputControlledDemo(): ReactElement {
  const [value, setValue] = useState<string>("")
  return (
    <NumberInput
      className="w-72"
      label="Controlled Value"
      onValueChange={({value}) => setValue(value)}
      placeholder="Placeholder"
      value={value}
    />
  )
}

Sizes

Customize size using the size prop. The default size is md.

<NumberInput
  aria-label="sm demo"
  className="w-56"
  placeholder="sm"
  size="sm"
  startIcon={Sigma}
/>
<NumberInput
  aria-label="md demo"
  className="w-64"
  placeholder="md"
  startIcon={Sigma}
/>
<NumberInput
  aria-label="lg demo"
  className="w-72"
  placeholder="lg"
  size="lg"
  startIcon={Sigma}
/>

Unit Selector

Add a unit selector to the number input by passing an array of options to the unitOptions prop.

The selected unit follows our controlled state pattern: use defaultUnit for uncontrolled state, or unit with onUnitChange for controlled state.

Price

<NumberInput
  className="w-72"
  defaultUnit="USD"
  label="Price"
  placeholder="0.00"
  unitOptions={currencyOptions}
  value="0"
/>

Error Text and Indicator

Error messages are displayed using two props:

invalid
errorText (or the NumberInput.ErrorText component when using the composite API)

The error text and indicator will only render when invalid is true.

Label

You must enter a value

<NumberInput
  className="w-72"
  errorText="You must enter a value"
  invalid={!value}
  label="Label"
  onValueChange={({value}) => setValue(value)}
  placeholder="Enter a value"
  value={value}
/>

API

<NumberInput.Root>

Prop	Type	Default
allowMouseWheel Whether to allow mouse wheel to change the value	boolean
allowOverflow Whether to allow the value to overflow the min/max range	boolean	true
children React children prop.	ReactNode
clampValueOnBlur Whether to clamp the value when the input loses focus (blur)	boolean	true
defaultUnit The initial unit when rendered. Use when you don't need to control the unit.	string
defaultValue The initial value of the input when rendered. Use when you don't need to control the value of the input.	string
dir The document's text/writing direction.	'ltr' \| 'rtl'	'ltr'
disabled Whether the input is disabled. When true, prevents user interaction and applies visual styling to indicate the disabled state.	boolean
endIcon lucide icon, positioned at the end of the input field.	\| LucideIcon \| ReactNode
focusInputOnChange Whether to focus the input when the value changes	boolean	true
form The associate form of the input element.	string
formatOptions The options to pass to the `Intl.NumberFormat` constructor	NumberFormatOptions
getRootNode A root node to correctly resolve document in custom environments. i.e., Iframes, Electron.	() => \| Node \| ShadowRoot \| Document
ids The ids of the elements that are associated with the input. These will be automatically generated if omitted.	Partial<{ decrementTrigger: string errorText: string hint: string incrementTrigger: string input: string label: string }>
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	\| 'text' \| 'tel' \| 'numeric' \| 'decimal'	"decimal"
invalid Controls the visual error state of the input. When true, applies semantic error styling to indicate validation failure.	boolean
locale The current locale. Based on the BCP 47 definition.	string	'en-US'
max The maximum value of the number input	number	Number.MAX_SAFE_INTEGER
min The minimum value of the number input	number	Number.MIN_SAFE_INTEGER
name The name attribute of the number input. Useful for form submission.	string
onFocusChange Function invoked when the number input is focused	( details: NumberInputFocusChangeDetails, ) => void
onUnitChange Function invoked when the selected unit changes	( unit: string, ) => void
onValueChange Function invoked when the value changes	( details: NumberInputValueChangeDetails, ) => void
onValueInvalid Function invoked when the value overflows or underflows the min/max range	( details: NumberInputValueInvalidDetails, ) => void
pattern The pattern used to check the element's value against	string	"[0-9]*(.[0-9]+)?"
readOnly Whether the input is read-only. When true, prevents user interaction while keeping the input focusable and visible.	boolean
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)
required Whether the input is required. When true, the input must have a value for form validation to pass.	boolean
size The size of the input field and its elements. Governs properties like font size, item padding, and icon sizes.	\| 'sm' \| 'md' \| 'lg'	'md'
spinOnPress Whether to spin the value when the increment/decrement button is pressed	boolean	true
startIcon lucide icon, positioned at the start of the input field.	\| LucideIcon \| ReactNode
step Amount to increment/decrement the value when using stepper buttons or arrow keys.	number	1
translations Specifies the localized strings that identify the accessibility elements and their states	{ decrementLabel?: string incrementLabel?: string valueText?: ( value: string, ) => string }
unit The controlled unit value	string
unitOptions Array of unit options to display in the unit selector	Array<{ displayText?: string label: string value: string }>
value The controlled value of the input	string

allowMouseWheel

Type

boolean

Description

Whether to allow mouse wheel to change the value

allowOverflow

Type

boolean

Description

Whether to allow the value to overflow the min/max range

children

Type

ReactNode

Description

React children prop.

clampValueOnBlur

Type

boolean

Description

Whether to clamp the value when the input loses focus (blur)

defaultUnit

Type

string

Description

The initial unit when rendered. Use when you don't need to control the unit.

defaultValue

Type

string

Description

The initial value of the input when rendered. Use when you don't need to control the value of the input.

dir

Type

'ltr' | 'rtl'

Description

The document's text/writing direction.

disabled

Type

boolean

Description

Whether the input is disabled. When true, prevents user interaction and applies visual styling to indicate the disabled state.

endIcon

Type

| LucideIcon
| ReactNode

Description

lucide icon, positioned at the end of the input field.

focusInputOnChange

Type

boolean

Description

Whether to focus the input when the value changes

form

Type

string

Description

The associate form of the input element.

formatOptions

Type

NumberFormatOptions

Description

The options to pass to the Intl.NumberFormat constructor

getRootNode

Type

() =>
| Node
| ShadowRoot
| Document

Description

A root node to correctly resolve document in custom environments. i.e., Iframes, Electron.

ids

Type

Partial<{
  decrementTrigger: string
  errorText: string
  hint: string
  incrementTrigger: string
  input: string
  label: string
}>

Description

The ids of the elements that are associated with the input. These will be automatically generated if omitted.

inputMode

Type

| 'text'
| 'tel'
| 'numeric'
| 'decimal'

Description

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

Type

boolean

Description

Controls the visual error state of the input. When true, applies semantic error styling to indicate validation failure.

locale

Type

string

Description

The current locale. Based on the BCP 47 definition.

max

Type

number

Description

The maximum value of the number input

min

Type

number

Description

The minimum value of the number input

name

Type

string

Description

The name attribute of the number input. Useful for form submission.

onFocusChange

Type

(
  details: NumberInputFocusChangeDetails,
) => void

Description

Function invoked when the number input is focused

onUnitChange

Type

(
  unit: string,
) => void

Description

Function invoked when the selected unit changes

onValueChange

Type

(
  details: NumberInputValueChangeDetails,
) => void

Description

Function invoked when the value changes

onValueInvalid

Type

(
  details: NumberInputValueInvalidDetails,
) => void

Description

Function invoked when the value overflows or underflows the min/max range

pattern

Type

string

Description

The pattern used to check the element's value against

readOnly

Type

boolean

Description

Whether the input is read-only. When true, prevents user interaction while keeping the input focusable and visible.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

required

Type

boolean

Description

Whether the input is required. When true, the input must have a value for form validation to pass.

size

Type

| 'sm'
| 'md'
| 'lg'

Description

The size of the input field and its elements. Governs properties like font size, item padding, and icon sizes.

spinOnPress

Type

boolean

Description

Whether to spin the value when the increment/decrement button is pressed

startIcon

Type

| LucideIcon
| ReactNode

Description

lucide icon, positioned at the start of the input field.

step

Type

number

Description

Amount to increment/decrement the value when using stepper buttons or arrow keys.

translations

Type

{
  decrementLabel?: string
  incrementLabel?: string
  valueText?: (
    value: string,
  ) => string
}

Description

Specifies the localized strings that identify the accessibility elements and their states

unit

Type

string

Description

The controlled unit value

unitOptions

Type

Array<{
  displayText?: string
  label: string
  value: string
}>

Description

Array of unit options to display in the unit selector

value

Type

string

Description

The controlled value of the input

<NumberInput>

The NumberInput component supports all props from NumberInput.Root, plus the additional props listed below.

Prop	Type
controlProps Props applied to the control element.	{ children?: ReactNode render?: \| Element \| (( props: Props, ) => Element) }
decrementTriggerProps Props applied to the decrement trigger button.	{ render?: \| Element \| (( props: Props, ) => Element) }
errorText Optional error that describes the element when invalid is true.	string
errorTextProps Props applied to the error text element.	{ icon?: \| LucideIcon \| ReactNode render?: \| Element \| (( props: Props, ) => Element) }
hint Optional hint describing the element. This element is automatically associated with the component's input element for accessibility.	ReactNode
hintProps Props applied to the label element.	{ id?: string render?: \| Element \| (( props: Props, ) => Element) }
incrementTriggerProps Props applied to the increment trigger button.	{ render?: \| Element \| (( props: Props, ) => Element) }
inputGroupProps Props applied to the input group element.	{ render?: \| Element \| (( props: Props, ) => Element) }
inputProps Props applied to the input element.	any
label Optional label describing the element. Recommended. This element is automatically associated with the component's input element for accessibility.	ReactNode
labelProps Props applied to the label element.	{ children?: ReactNode id?: string required?: boolean }
placeholder HTML placeholder attribute, passed to the underlying input element.	string
unitSelectProps Props applied to the unit select element.	{id?: string}

controlProps

Type

{
  children?: ReactNode
  render?:
    | Element
    | ((
        props: Props,
      ) => Element)
}

Description

Props applied to the control element.

decrementTriggerProps

Type

{
  render?:
    | Element
    | ((
        props: Props,
      ) => Element)
}

Description

Props applied to the decrement trigger button.

errorText

Type

string

Description

Optional error that describes the element when invalid is true.

errorTextProps

Type

{
  icon?:
    | LucideIcon
    | ReactNode
  render?:
    | Element
    | ((
        props: Props,
      ) => Element)
}

Description

Props applied to the error text element.

hint

Type

ReactNode

Description

Optional hint describing the element. This element is automatically associated with the component's input element for accessibility.

hintProps

Type

{
  id?: string
  render?:
    | Element
    | ((
        props: Props,
      ) => Element)
}

Description

Props applied to the label element.

incrementTriggerProps

Type

{
  render?:
    | Element
    | ((
        props: Props,
      ) => Element)
}

Description

Props applied to the increment trigger button.

inputGroupProps

Type

{
  render?:
    | Element
    | ((
        props: Props,
      ) => Element)
}

Description

Props applied to the input group element.

inputProps

Type

any

Description

Props applied to the input element.

label

Type

ReactNode

Description

Optional label describing the element. Recommended. This element is automatically associated with the component's input element for accessibility.

labelProps

Type

{
  children?: ReactNode
  id?: string
  required?: boolean
}

Description

Props applied to the label element.

placeholder

Type

string

Description

HTML placeholder attribute, passed to the underlying input element.

unitSelectProps

Type

{id?: string}

Description

Props applied to the unit select element.

Data Structures

UnitOption

Each unit option object accepts the following properties:

Prop	Type
displayText Full text shown in dropdown menu. Defaults to label if not provided.	string
label Short label shown on trigger button.	string
value Internal value identifier.	string