NumberField

NumberField is a numeric input with optional label, description, error message, min/max/step, and increment/decrement stepper buttons. Use it in forms for quantities, amounts, or percentages.

Installation

npm install --save @godaddy/antares

Props

The NumberField component accepts the following props:

NameTypeDefault

hideStepper?boolean | undefinedfalse

When true, hides the increment/decrement stepper buttons.

placeholder?string | undefined—

Placeholder when the value is empty.

validationBehavior?"native" | "aria" | undefined'native'

Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.

decrementAriaLabel?string | undefined—

A custom aria-label for the decrement button. If not provided, the localized string "Decrement" is used.

incrementAriaLabel?string | undefined—

A custom aria-label for the increment button. If not provided, the localized string "Increment" is used.

isWheelDisabled?boolean | undefined—

Enables or disables changing the value with scroll.

formatOptions?Intl.NumberFormatOptions | undefined—

Formatting options for the value displayed in the number field. This also affects what characters are allowed to be typed by the user.

commitBehavior?"validate" | "snap" | undefined'snap'

Controls the behavior of the number field when the user blurs the field after editing. 'snap' will clamp the value to the min/max values, and snap to the nearest step value. 'validate' will not clamp the value, and will validate that the value is within the min/max range and on a valid step.

isDisabled?boolean | undefined—

Whether the input is disabled.

isReadOnly?boolean | undefined—

Whether the input can be selected but not changed by the user.

isRequired?boolean | undefined—

Whether user input is required on the input before form submission.

isInvalid?boolean | undefined—

Whether the input value is invalid.

validate?((value: number) => ValidationError | true | null | undefined) | undefined—

A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead.

autoFocus?boolean | undefined—

Whether the element should receive focus on render.

onFocus?((e: React.FocusEvent<Element, Element>) => void) | undefined—

Handler that is called when the element receives focus.

onBlur?((e: React.FocusEvent<Element, Element>) => void) | undefined—

Handler that is called when the element loses focus.

onFocusChange?((isFocused: boolean) => void) | undefined—

Handler that is called when the element's focus status changes.

onKeyDown?((e: KeyboardEvent) => void) | undefined—

Handler that is called when a key is pressed.

onKeyUp?((e: KeyboardEvent) => void) | undefined—

Handler that is called when a key is released.

value?number | undefined—

The current value (controlled).

defaultValue?number | undefined—

The default value (uncontrolled).

onChange?((value: number) => void) | undefined—

Handler that is called when the value changes.

minValue?number | undefined—

The smallest value allowed for the input.

maxValue?number | undefined—

The largest value allowed for the input.

step?number | undefined—

The amount that the input value changes with each increment or decrement "tick".

id?string | undefined—

The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id).

className?ClassNameOrFunction<NumberFieldRenderProps> | undefined'react-aria-NumberField'

The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state.

name?string | undefined—

The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname).

form?string | undefined—

The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form).

style?StyleOrFunction<NumberFieldRenderProps> | undefined—

The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state.

render?DOMRenderFunction<"div", NumberFieldRenderProps> | undefined—

Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.

slot?string | null | undefined—

A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent.

label?string | undefined—

Label text shown above the frame.

description?string | undefined—

Helper text shown below the frame.

errorMessage?string | undefined—

Error message shown when invalid.

Examples

Basic

Minimal usage with label, placeholder, and min/max.

import { NumberField, type NumberFieldProps } from '@godaddy/antares';export function NumberFieldBasicExample(props: NumberFieldProps) {  return <NumberField label="Quantity" placeholder="0" defaultValue={0} {...props} />;}

Quantity

Controlled

Use value and onChange for controlled state.

import { useState } from 'react';import { NumberField, Text } from '@godaddy/antares';export function NumberFieldControlledExample() {  const [value, setValue] = useState(10);  return (    <>      <NumberField label="Quantity" minValue={0} maxValue={100} value={value} onChange={setValue} />      <Text>        <strong>Value:</strong> {value ?? '(empty)'}      </Text>    </>  );}

Quantity

Value: 10

Invalid

Use isInvalid with errorMessage for validation feedback.

import { NumberField } from '@godaddy/antares';export function NumberFieldInvalidExample() {  return (    <NumberField      label="Quantity"      minValue={0}      maxValue={100}      errorMessage="Please enter a value between 0 and 100"      isInvalid      isRequired    />  );}

Quantity *

Please enter a value between 0 and 100

Disabled

Use isDisabled to prevent input.

import { NumberField } from '@godaddy/antares';export function NumberFieldDisabledExample() {  return <NumberField label="Quantity" defaultValue={42} minValue={0} maxValue={100} isDisabled />;}

Quantity

Hide stepper

Use hideStepper to show only the input without +/- buttons.

import { NumberField } from '@godaddy/antares';export function NumberFieldHideStepperExample() {  return (    <NumberField      label="Quantity"      description="Enter a value between 0 and 100."      placeholder="0"      minValue={0}      maxValue={100}      hideStepper    />  );}

Quantity

Enter a value between 0 and 100.

Value scale

Use minValue, maxValue, and step to set the allowed values. Steps are calculated from the minimum value.

import { NumberField } from '@godaddy/antares';export function NumberFieldValueScaleExample() {  return (    <NumberField      label="Step value"      description="Steps are from the minimum: minValue={2}, step={3} gives 2, 5, 8, 11, …"      placeholder="2"      minValue={2}      maxValue={20}      step={3}    />  );}

Step value

Steps are from the minimum: minValue={2}, step={3} gives 2, 5, 8, 11, …

Format options (numbering system)

By default, NumberField displays the value using the numbering system for the user's locale. Use the formatOptions prop to override the numbering system by setting the Unicode numbering system locale extension.

import { NumberField } from '@godaddy/antares';const devanagariFormatOptions = Intl.NumberFormat('hi-IN-u-nu-deva').resolvedOptions();export function NumberFieldFormatOptionsExample() {  return (    <NumberField      label="Number (Devanagari)"      description="By default, NumberField uses the user's locale. Use formatOptions to override with a Unicode numbering system locale extension (e.g. nu-deva)."      hideStepper      value={1024}      formatOptions={devanagariFormatOptions}    />  );}

Number (Devanagari)

By default, NumberField uses the user's locale. Use formatOptions to override with a Unicode numbering system locale extension (e.g. nu-deva).

Accessibility

Keyboard

When focus is in the input (and the field is not read-only), keyboard behavior follows common spinbutton-style conventions:

Arrow Up / Arrow Down (or Up / Down): increase or decrease by step
Page Up / Page Down: larger increase or decrease when supported
Home / End: jump to minValue or maxValue when those props are set

Stepper buttons are real buttons and follow standard button keyboard activation. Use incrementAriaLabel and decrementAriaLabel when the default labels are not enough in your locale or UI.

ARIA and labeling

The input is associated with the visible label and optional description and error content for assistive technologies.
Invalid and required states are exposed to assistive technologies when you use isInvalid, errorMessage, and isRequired.
Set isWheelDisabled if the value should not change when the user scrolls with a pointer wheel while the field is focused.

Best practices

Pair isInvalid with errorMessage so users get both visual and programmatic feedback.
Remember valid steps start from minValue.
Use isDisabled when the value cannot be changed; use isReadOnly when the value should be visible but not editable. Do not use them interchangeably.
For currency or units, ensure formatOptions (and locale) match what users are allowed to type.

NumberField

On this page