NumberInput

Components/Form

Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/numberinput

Overview

Copy

Number inputs allow users to enter and edit numeric values in a single line input field. The value can be inserted using the keyboard or incremented using the arrow controls.

Do

  • Use it to enter custom numeric values, e.g., amount, price, quantity.
  • Use it to adjust values by a specific amount, e.g., the number of items in a shopping cart.

Don't

  • Don't use it to enter numerals that don't indicate quantity or measurements, e.g., phone numbers or postal codes. Use regular <Input/> instead.
  • Don't use it to enter dates and times. Use <DatePicker/> or <TimeInput/> instead.

Feature examples

Size

Adjust the size using the size prop. There are 3 supported sizes:

  • When the input needs to be emphasized, like in onboarding flows, use large.
  • In most cases, use the default medium.
  • For dense and narrow layouts where space is tight, use small.
Copy

Border

Style the field using the border prop. It supports 4 styles:

  • For most common cases, like forms, use standard.
  • To build inputs that can be used to filter data, use round.
  • Use bottomLine to create an editable, underlined title field.
  • When a component provides its own hover and focus styles, such as a table or spreadsheet cells, use none.
Copy

Status

Control the status of the input using the status prop. It supports 3 states:

  • error demonstrates that a required input is missing something or the entry was invalid.
  • warning highlights an input value that might have a significant impact to a user.
  • loading shows when an input value is being uploaded to the server.
Copy

Status message

Add text that explains the status or what action the user should take with the statusMessage prop.

Showing the status message inline, directly below the input is preferred in all default cases.

  • To add an accessible inline message, wrap the component in a <FormField/> and add the statusMessage.
  • To add a status message in a tooltip that requires users to hover on the icon, use the statusMessage prop. Control tooltip placement with tooltipPlacement prop.

View more inline status message examples in <FormField/>.

Copy

Prefix and suffix

Add text, icons or a button at the beginning or end of the input field using prefix and suffix.

Copy

Read-only and disabled

Inputs can also be made read-only or disabled entirely.

  • readOnly disables the field, so users can't enter new values. The current value can still be copied.
  • disabled removes all interactions and creates a disabled input state. Use it to highlight functions that are unavailable.
Copy

Clear button

Enable a button that lets users easily clear the input value by using the clearButton prop. Use it when the input value is optional or has to be cleared often.

Copy

Increment by steps

Use the step prop to specify what the increments are when clicking up or down on the arrows.

The arrows controls can be hidden with hideStepper. When the arrows are hidden, the field value can still be incremented by the set step when the field is changed using the arrow keys on the keyboard.

Copy

Min and max values

If the user inputs something outside of the minimum or maximum, explain that it's invalid using the invalidMessage prop.

Get informed about invalid message events by using the onInvalid callback function.

Copy

Developer examples

Controlled

Use NumberInput in controlled mode by passing value and onChange props.

Copy

Range validation

The min and max properties enable built-in range validation, so no need to add onChange and value.

Users will still be able to enter invalid numbers, but will be notified that what they entered is invalid. Set the error message using invalidMessage.

Don't allow users to submit a form with an invalid input value. Use onInvalid to get an invalid event.

Copy

Integrating with react-hook-form

react-hook-form reduces the amount of code you need to write while removing unnecessary re-renders. The preview here demonstrates form validation in action while using the number input.

Copy

Common use case examples

Settings panel

Use number input with other components like <Slider/> in a <FieldSet/> wrapper to group them together and let users define the exact numerical value.

Copy

Compound input

Stack items next to each other with <Box/> when fields represent the same data, or when a change in one input affects one or more other fields.

Copy

Disabled stepper

Disable the arrows once the minimum or maximum value has been reached.

Copy

Accessibility examples

Helper text

To help users enter the correct value, use helper text below the input which describes the constraints.

This will help prevent user errors.

Copy

Code

Copy

Props

NameTypeDefaultDescription
ariaControlsstring—Associate a control with the regions that it controls.
ariaDescribedbystring—Associate a region with its descriptions. Similar to aria-controls but instead associating descriptions to the region and description identifiers are separated with a space.
ariaLabelstring—Define a string that labels the current element in case where a text label isn't visible on the screen.
autocompletestring—Sets the value of the native autocomplete attribute, for example off or email.
autoFocusboolean—Focus the element on mount (standard React input autoFocus)
autoSelectboolean—Automatically selects the entire input text.
backgroundColorstring—Sets the background color of the input. Accepts any CSS color value.
border"none" | "standard" | "round" | "bottomLine"—Control the border style of input.
clearButtonboolean—Displays clear button (X) on a non-empty input.
clearButtonAriaLabelstring—Aria label for the clear button.
clearButtonTooltipContentReactNode—When provided, hovering displays a tooltip with this content.
clearButtonTooltipPropsTooltipCommonProps—Clear button tooltip props.
customInputReactNode | Function—Render a custom input instead of the default html input tag.
dataHookstring—Applies a data-hook HTML attribute that can be used in the tests.
defaultValuestring | number—Defines the initial value of an input.
disabledboolean—Specifies whether input should be disabled or not.
disableEditingboolean—Restricts input editing.
enterKeyHint"search" | "enter" | "done" | "go" | "next" | "previous" | "send"—Sets the label of the virtual keyboard's enter key on touch devices.
focusOnClearClickboolean—Specifies whether to focus the field when clear button is clicked.
hideStatusSuffixboolean—Specifies whether status suffix should be hidden.
hideStepperboolean—Specifies whether stepper should be hidden.
idstring—Assigns a unique identifier for the root element.
inputmodestring'numeric'Sets the native inputmode attribute, which picks the virtual keyboard on touch devices.
inputRef(input: HTMLInputElement) => void | MutableRefObject<HTMLInputElement | null>—Ref to the underlying <input> DOM element. Accepts callback and object refs. Use for input masking libraries such as use-mask-input. Memoize callback refs to avoid reattaching on every render.
invalidMessagestring—Enables internal validation and defines a message to display when user types invalid value.
maxnumber—Sets a maximum value of an input. Similar to html5 max attribute.
maxLengthnumber—Sets the maximum number of characters that can be inserted to a field.
menuArrowboolean—Specifies whether input should have a dropdown menu arrow on the right side.
minnumber—Sets a minimum value of an input. Similar to HTML5 min attribute.
namestring—Reference element data when a form is submitted.
noLeftBorderRadiusboolean—Specifies whether input shouldn't have rounded corners on its left.
noRightBorderRadiusboolean—Specifies whether input shouldn't have rounded corners on its right.
onBlurFocusEventHandler—Defines a standard input onBlur callback.
onChange(value: number | null, stringValue: string) => void—Defines a standard input onChange callback.
onClear(event: KeyboardEvent<HTMLButtonElement> | MouseEvent<HTMLButtonElement, MouseEvent>) => void—Displays clear button (X) on a non-empty input and calls a callback function.
onCompositionChange(isComposing: boolean) => void—Defines a callback function called on compositionstart/compositionend events.
onEnterPressedKeyboardEventHandler<HTMLInputElement>—Defines a callback handler that is called when the user presses -enter-.
onEscapePressedKeyboardEventHandler<HTMLInputElement>—Defines a callback handler that is called when the user presses -escape-.
onFocus(e?: FocusEvent<HTMLInputElement, Element> | undefined) => void—Defines a standard input onFocus callback.
onInputClickedMouseEventHandler—Defines a standard input onClick callback.
onInvalid(stringValue: string, { validationType, value, }: { validationType?: "outOfBoundsError" | "formatError" | undefined; value: string; }) => void—Defines a callback function which is called on cases when invalid value is typed. - return { stringValue: string, { validationType: 'formatError' | 'outOfBoundsError', value: string }} - validationType - type 'formatError' is set when value is in the wrong format - type 'outOfBoundsError' is set when min or max props are used and value doesn't match the bounds - value - is set to current input value
onKeyDownKeyboardEventHandler<HTMLInputElement>—Defines a standard input onKeyDown callback.
onKeyUpKeyboardEventHandler<HTMLInputElement>—Defines a standard input onKeyUp callback.
onPasteClipboardEventHandler<HTMLInputElement>—Defines a callback handler that is called when user pastes text from a clipboard (using a mouse or keyboard shortcut)
patternstring—Sets a pattern that typed value must match to be valid (regex)
placeholderstring—Sets a placeholder message to display.
prefixReactNode—Pass a component you want to show as the prefix of the input, e.g., text, icon.
readOnlyboolean—Specifies whether input is read only.
requiredboolean—Specifies whether input is mandatory.
rtlboolean—Specifies text direction. If true, the text is displayed from right to left.
size"small" | "tiny" | "medium" | "large"—Controls the size of the input.
status"error" | "warning" | "loading"—Specify the status of a field.
statusMessageReactNode—Defines the message to display on status icon hover. If not given or empty, no tooltip is displayed.
statusMessageTooltipPropsTooltipCommonProps—Status message tooltip props.
stepnumber | number[]—Specifies the interval between number values.
strictboolean—Has no effect.
suffixReactNode—Pass a component you want to show as the suffix of the input, e.g., text, icon.
tabIndexnumber—Indicates that element can be focused and where it participates in sequential keyboard navigation.
textOverflow"ellipsis" | "clip"—Handles text overflow behavior. It can either clip (default) or display ellipsis.
tooltipPlacement"right" | "left" | "top" | "bottom" | "auto" | "auto-start" | "auto-end" | "top-start" | "top-end" | "right-start" | "right-end" | "bottom-end" | "bottom-start" | "left-end" | "left-start"—Controls placement of a status tooltip.
typestring—Specifies the type of <input/> element to display. Default is text.
valuestring | number—Specifies the current value of the element.
withSelectionboolean—

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
clickOnIncrementClick on ticker up
clickOnDecrementClick on ticker down
isDownDisabledCheck if ticker down is disabled
isUpDisabledCheck if ticker up is disabled
click—
getInputAttribute—
getInputElementClasses—
suffixComponentExists—
getRootElementClasses—
getAriaDescribedby—
getAriaLabel—
getName—
getMaxLength—
getType—
getAriaControls—
clickIconAffix—
clickCustomAffix—
getCustomAffixText—
hasSuffix—
getClearButtonTooltipContent—
prefixComponentExists—
hasPrefix—
hasClearButton—
clickClear—
getValue—
getText—
getPattern—
getPlaceholder—
isOfSize—
getSize—
isDisabled—
isHoveredStyle—
isFocusedStyle—
getRequired—
enterText—
getAutocomplete—
getDefaultValue—
getTabIndex—
isCustomInput—
getReadOnly—
getDisabled—
getTextOverflow—
focus—
blur—
keyUp—
keyDown—
pressKey—
paste—
copy—
wheel—
trigger—
isFocus—
clickMenuArrow—
hasMenuArrow—
isRTL—
getCursorLocation—
clearText—
clickOutside—
isMasked—
isSelected—
hasStatusReturn true if there's a status
getStatusMessageIf there's a status message, returns its text value
existsChecks whether the component found with the given data hook.
elementGets the component root element.
baseReturns UniDriver for the base element.

Changelog

  • 1.340.0 (2026-10-21) — maintenance release, no component-specific changes
  • 1.339.0 (2026-10-19) — maintenance release, no component-specific changes
  • 1.338.0 (2026-10-15) — maintenance release, no component-specific changes
  • 1.336.0 (2026-10-13) — maintenance release, no component-specific changes
  • 1.331.0 (2026-10-01) — maintenance release, no component-specific changes
  • 1.330.3 (2026-09-29) — maintenance release, no component-specific changes
  • 1.330.1 (2026-09-28) — maintenance release, no component-specific changes
  • 1.330.0 (2026-09-28) — maintenance release, no component-specific changes
  • 1.325.0 (2026-09-17) — maintenance release, no component-specific changes
  • 1.312.0 (2026-08-14) — maintenance release, no component-specific changes
  • 1.310.0 (2026-08-10) — maintenance release, no component-specific changes
  • 1.292.0 (2026-06-22) — maintenance release, no component-specific changes
  • 1.289.0 (2026-06-17) — maintenance release, no component-specific changes
  • 1.288.0 (2026-06-15) — maintenance release, no component-specific changes
  • 1.282.0 (2026-05-27) — feat: add tooltip props, deprecate tooltipPlacement (#16299)
  • 1.277.0 (2026-05-07) — maintenance release, no component-specific changes
  • 1.272.0 (2026-04-27) — maintenance release, no component-specific changes
  • 1.266.0 (2026-04-07) — maintenance release, no component-specific changes
  • 1.260.0 (2026-03-17) — maintenance release, no component-specific changes
  • 1.245.0 (2026-01-06) — fix: fix disabled states of ticker and local/controlled states and suffix testkit (#15658)
  • 1.213.0 (2025-08-19) — maintenance release, no component-specific changes
  • 1.204.1 (2025-07-10) — maintenance release, no component-specific changes
  • 1.184.0 (2025-04-30) — fix: when min is 0 and value is smaller increment broken (#14801)
  • 1.178.0 (2025-04-08) — feat: add inc/dec handlers (#14675)
  • 1.169.0 (2025-03-10) — maintenance release, no component-specific changes
  • 1.159.0 (2025-02-06) — fix: type (#14506)
  • 1.155.0 (2025-01-23) — fix: tickers(up/down) disabled visual state (#14457)
  • 1.149.1 (2024-12-20) — maintenance release, no component-specific changes
  • 1.138.1 (2024-10-30) — maintenance release, no component-specific changes
  • 1.134.0 (2024-10-18) — fix: set to min value when incrementing (#14220)
  • 1.133.0 (2024-10-14) — maintenance release, no component-specific changes
  • 1.126.0 (2024-09-09) — fix: decimal values & NaN fix (#14100)
  • 1.123.1 (2024-09-05) — maintenance release, no component-specific changes
  • 1.120.1 (2024-08-08) — fix: call onChange when invalid in controlled mode (#14022)
  • 1.117.0 (2024-07-25) — fix: when value and onChange is provided controlled mode is on (#13978)
  • 1.115.0 (2024-07-17) — maintenance release, no component-specific changes
  • 1.109.2 (2024-06-17) — maintenance release, no component-specific changes
  • 1.98.0 (2024-03-15) — fix: inputRef function not work well (#13458)
  • 1.97.2 (2024-03-04) — fix: fixed propType which was out of sync with types (#13411)
  • 1.97.0 (2024-02-26) — maintenance release, no component-specific changes
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 26 October 2026

Did this help?