Getting Started
InstallationVersioning
Integrations
ESLintTailwind CSS
Theming & Patterns
Composition
Polymorphic ComponentsRender Props
Components
OverviewAccordionAlert Banner
AvatarBreadcrumbsButtonButton GroupCard
Beta
CheckboxCheckbox Group
CollapsibleComboboxDialogDividerDrawerFile Input
Beta
Header BarIconIcon ButtonInline Icon ButtonInline Notification
LinkMenuNumber InputPaginationPassword InputPopoverProgressProgress RingRadioSegmented ControlSelectSide NavSliderStepper
Beta
SwitchSwitch Group
TableTabsTagText Area
Text InputToast NotificationTooltipTree

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.

<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.

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.

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.

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.

<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.

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}
/>

Explorer

Some contextual help here

Component Anatomy

Hover to highlight, click to view API

rootlabelinput-groupinputcontrolincrement-triggerdecrement-triggerhint

API

<NumberInput>

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

PropType
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.

Composite API

<NumberInput.Root>

PropTypeDefault
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.Label>

                      PropType
                      children
                      React children prop.
                      ReactNode
                      id
                      id attribute. If omitted, a unique identifier will be automatically generated for accessibility.
                      string
                      required
                      Whether the input is required. When true, the field will show a required indicator.
                      boolean
                      children
                      Type
                      ReactNode
                      Description
                      React children prop.
                      id
                      Type
                      string
                      Description
                      id attribute. If omitted, a unique identifier will be automatically generated for accessibility.
                      required
                      Type
                      boolean
                      Description
                      Whether the input is required. When true, the field will show a required indicator.

                      <NumberInput.InputGroup>

                      PropType
                      render
                      Allows you to replace the component's HTML element with a different tag or component. Learn more
                      | ReactElement
                      | ((
                          props: object,
                        ) => ReactElement)
                      render
                      Type
                      | ReactElement
                      | ((
                          props: object,
                        ) => ReactElement)
                      Description
                      Allows you to replace the component's HTML element with a different tag or component. Learn more

                      <NumberInput.Input>

                      <NumberInput.Control>

                      PropType
                      children
                      React children prop.
                      ReactNode
                      render
                      Allows you to replace the component's HTML element with a different tag or component. Learn more
                      | ReactElement
                      | ((
                          props: object,
                        ) => ReactElement)
                      children
                      Type
                      ReactNode
                      Description
                      React children prop.
                      render
                      Type
                      | ReactElement
                      | ((
                          props: object,
                        ) => ReactElement)
                      Description
                      Allows you to replace the component's HTML element with a different tag or component. Learn more

                      <NumberInput.IncrementTrigger>

                      PropType
                      render
                      Allows you to replace the component's HTML element with a different tag or component. Learn more
                      | ReactElement
                      | ((
                          props: object,
                        ) => ReactElement)
                      render
                      Type
                      | ReactElement
                      | ((
                          props: object,
                        ) => ReactElement)
                      Description
                      Allows you to replace the component's HTML element with a different tag or component. Learn more

                      <NumberInput.DecrementTrigger>

                      PropType
                      render
                      Allows you to replace the component's HTML element with a different tag or component. Learn more
                      | ReactElement
                      | ((
                          props: object,
                        ) => ReactElement)
                      render
                      Type
                      | ReactElement
                      | ((
                          props: object,
                        ) => ReactElement)
                      Description
                      Allows you to replace the component's HTML element with a different tag or component. Learn more

                      <NumberInput.Hint>

                      PropType
                      id
                      id attribute. If omitted, a unique identifier will be automatically generated for accessibility.
                      string
                      render
                      Allows you to replace the component's HTML element with a different tag or component. Learn more
                      | ReactElement
                      | ((
                          props: object,
                        ) => ReactElement)
                      id
                      Type
                      string
                      Description
                      id attribute. If omitted, a unique identifier will be automatically generated for accessibility.
                      render
                      Type
                      | ReactElement
                      | ((
                          props: object,
                        ) => ReactElement)
                      Description
                      Allows you to replace the component's HTML element with a different tag or component. Learn more

                      <NumberInput.ErrorText>

                      PropType
                      icon
                      An icon to display next to the error text.
                      | LucideIcon
                      | ReactNode
                      render
                      Allows you to replace the component's HTML element with a different tag or component. Learn more
                      | ReactElement
                      | ((
                          props: object,
                        ) => ReactElement)
                      icon
                      Type
                      | LucideIcon
                      | ReactNode
                      Description
                      An icon to display next to the error text.
                      render
                      Type
                      | ReactElement
                      | ((
                          props: object,
                        ) => ReactElement)
                      Description
                      Allows you to replace the component's HTML element with a different tag or component. Learn more

                      <NumberInput.ErrorIndicator>

                      PropTypeDefault
                      icon
                      lucide-react icon or ReactNode.
                      | LucideIcon
                      | ReactNode
                      CircleAlert
                      render
                      Allows you to replace the component's HTML element with a different tag or component. Learn more
                      | ReactElement
                      | ((
                          props: object,
                        ) => ReactElement)
                      icon
                      Type
                      | LucideIcon
                      | ReactNode
                      Description
                      lucide-react icon or ReactNode.
                      render
                      Type
                      | ReactElement
                      | ((
                          props: object,
                        ) => ReactElement)
                      Description
                      Allows you to replace the component's HTML element with a different tag or component. Learn more

                      <NumberInput.UnitSelect>

                      PropType
                      id
                      id attribute. If omitted, a unique identifier will be automatically generated for accessibility.
                      string
                      id
                      Type
                      string
                      Description
                      id attribute. If omitted, a unique identifier will be automatically generated for accessibility.

                      Data Structures

                      UnitOption

                      Each unit option object accepts the following properties:

                      PropType
                      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
                      displayText
                      Type
                      string
                      Description
                      Full text shown in dropdown menu. Defaults to label if not provided.
                      label
                      Type
                      string
                      Description
                      Short label shown on trigger button.
                      value
                      Type
                      string
                      Description
                      Internal value identifier.
                      Last updated on by Ryan Bower
                      Menu
                      Pagination
                      Examples
                      Simple
                      Composite
                      Min and Max values
                      Step interval
                      States
                      Controlled Value
                      Sizes
                      Unit Selector
                      Error Text and Indicator
                      Explorer
                      API
                      <NumberInput>
                      Composite API
                      <NumberInput.Root>
                      <NumberInput.Label>
                      <NumberInput.InputGroup>
                      <NumberInput.Input>
                      <NumberInput.Control>
                      <NumberInput.IncrementTrigger>
                      <NumberInput.DecrementTrigger>
                      <NumberInput.Hint>
                      <NumberInput.ErrorText>
                      <NumberInput.ErrorIndicator>
                      <NumberInput.UnitSelect>
                      Data Structures
                      UnitOption
                      Copyright © 2026 QUALCOMM incorporated. All rights reserved. This site is built with QUI Docs. Head over to the template repository to start building.