NumberInput·component·@astryxdesign/core

Number Input

A form input for numeric values with built-in validation, min/max constraints, and step controls. Use NumberInput for quantities, measurements, percentages, and similar inputs.

Open in Playground @astryxdesign/core/NumberInput

Showcases and examples

5 documented examples

Number Input

A number input for quantity entry.

Open Playground ↗

Preview loads on approachPreview loads on approach

Exact source · number-input-showcase

// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

import {useState} from 'react';
import {NumberInput} from '@astryxdesign/core/NumberInput';

export default function NumberInputShowcase() {
  const [value, setValue] = useState<number | null>(0);
  return (
    <div style={{width: 300}}>
      <NumberInput
        label="Quantity"
        placeholder="Enter quantity"
        value={value}
        onChange={setValue}
        formatValue={number => `${number} items`}
        hasNumberSteppers
      />
    </div>
  );
}

Usage

A form input for numeric values with built-in validation, min/max constraints, and step controls. Use NumberInput for quantities, measurements, percentages, and similar inputs.

Let people paste formatted numbers: a pasted 1,234,234,234 is read under the field's locale and commits as 1234234234 on blur. Typing is never intercepted.
Set min, max, and step to guide users toward valid values.
Show units (e.g. "%" or "GB") so users know what the number represents.
Set isWheelEnabled={false} when the input appears in a scrolling surface where wheel gestures should always scroll the page.
Use NumberInput for free-form text that happens to contain numbers; use TextInput instead.
Set both isOptional and isRequired on the same field.
Wrap a disabled NumberInput in Tooltip to explain why it's disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.

Typed props

Prop	Type and behavior
`label`	`string` · required Label text for the input (always rendered for accessibility).
`value`	`number \| null \| undefined` · required Current value of the input.
`onChange`	`(value: number) => void` · required Callback fired when a valid text edit commits on blur or Enter, or when a step or clear control changes the value.
`size`	`'sm' \| 'md' \| 'lg'` · default 'md' Size variant.
`isLabelHidden`	`boolean` Visually hide the label (still accessible to screen readers).
`description`	`string` Description text displayed between the label and input.
`isOptional`	`boolean` Whether the field is optional (mutually exclusive with isRequired).
`onKeyDown`	`(e: KeyboardEvent<HTMLInputElement>) => void` Callback fired on keydown events on the input.
`isRequired`	`boolean` Whether the field is required (mutually exclusive with isOptional).
`isDisabled`	`boolean` Whether the input is disabled.
`isReadOnly`	`boolean` · default false Makes the input read-only: the value is shown at full opacity and still submits with the form, but cannot be edited. Unlike isDisabled, a read-only input is not dimmed and stays in the tab order. Stepping is off in every form while read-only: arrow keys, the wheel, and the number steppers. isDisabled takes precedence when both are set.
`disabledMessage`	`string` Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (the field becomes read-only). Use this instead of wrapping a disabled NumberInput in Tooltip.
`placeholder`	`string` Placeholder text.
`labelTooltip`	`string` Tooltip text to display in an info icon at the end of the label.
`startIcon`	`IconType` Icon to display at the start of the input. See `astryx docs icons` for valid semantic names.
`labelIcon`	`IconType` Icon to display before the label text. See `astryx docs icons` for valid semantic names.
`status`	`{type: 'error' \| 'warning' \| 'success', message?: string}` Validation status with optional message.
`statusVariant`	`'attached' \| 'detached' \| 'tooltip'` · default 'attached' How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing; tooltip hides the message box and surfaces it in a tooltip on the status icon.
`min`	`number \| null` Minimum value allowed. A smaller entry commits at this value on blur or Enter.
`max`	`number \| null` Maximum value allowed. A larger entry commits at this value on blur or Enter.
`step`	`number \| null` · default 1 Step increment for the input.
`formatValue`	`(value: number) => string` Formats the committed value while the input is not focused. The raw numeric value is shown on focus for editing and the formatted value is exposed through aria-valuetext.
`isWheelEnabled`	`boolean` · default true Whether scrolling the wheel over the focused input steps the value. Disable this when page scrolling should always take priority.
`hasNumberSteppers`	`boolean` · default false Shows increment and decrement buttons at the end of the input.
`units`	`string \| null` Units text to display at the end of the input (e.g., "%" or "GB").
`isIntegerOnly`	`boolean` Only allow integer values (no floating point).
`hasClear`	`boolean` · default false Shows a clear (×) button when the input has a value. When true, the onChange callback also accepts null to signal the user cleared the input.
`htmlName`	`string` HTML name attribute for form submissions.
`autoComplete`	`string` HTML autocomplete attribute.
`width`	`SizeValue` Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned.
`hasAutoFocus`	`boolean` Whether to focus the input on mount.
`onFocus`	`(e: FocusEvent<HTMLInputElement>) => void` Callback fired when the input receives focus.
`onBlur`	`(e: FocusEvent<HTMLInputElement>) => void` Callback fired when the input loses focus.
`onEnter`	`() => void` Callback fired when the user presses the Enter key.

Anatomy

Label · required

The label for the number input.

Description · optional

Additional description text below the label.

Icon · optional

An optional icon within the input.

Placeholder · optional

Placeholder text shown when the input is empty.

Number steppers · optional

Optional buttons that increment or decrement by the configured step.

Theming

Targets

astryx-number-input

Visual props: size, status

States: disabled, readonly

Derived properties

padding

Expands: container

borderRadius

Uses --_field-radius.