NumberInput

Numeric input field with optional min/max bounds and step control.

Examples

Default

Quantity

function ControlledNumberInput({
  value: initialValue = null,
  ...args
}: ControlledNumberInputProps): React.JSX.Element {
  const [value, setValue] = useState<number | null>(initialValue);

  return (
    <NumberInput
      {...(args as NumberInputProps)}
      onChange={setValue}
      value={value}
    />
  );
}

<ControlledNumberInput {...args} />

Wheel Behavior

Wheel disabled (default): scrolling over the focused input scrolls this panel.

Wheel disabled

Wheel enabled: scrolling over the focused input changes its value.

Wheel enabled

function ControlledNumberInput({
  value: initialValue = null,
  ...args
}: ControlledNumberInputProps): React.JSX.Element {
  const [value, setValue] = useState<number | null>(initialValue);

  return (
    <NumberInput
      {...(args as NumberInputProps)}
      onChange={setValue}
      value={value}
    />
  );
}

<div className={wheelStoryStyles.grid}>
  <div className={wheelStoryStyles.panel}>
    <p className={wheelStoryStyles.text}>
      Wheel disabled (default): scrolling over the focused input scrolls
      this panel.
    </p>
    <div className={wheelStoryStyles.scrollArea}>
      <div className={wheelStoryStyles.spacer} />
      <ControlledNumberInput label="Wheel disabled" value={2} />
      <div className={wheelStoryStyles.spacer} />
    </div>
  </div>
  <div className={wheelStoryStyles.panel}>
    <p className={wheelStoryStyles.text}>
      Wheel enabled: scrolling over the focused input changes its value.
    </p>
    <div className={wheelStoryStyles.scrollArea}>
      <div className={wheelStoryStyles.spacer} />
      <ControlledNumberInput
        isWheelEnabled
        label="Wheel enabled"
        value={2}
      />
      <div className={wheelStoryStyles.spacer} />
    </div>
  </div>
</div>

With Units

Storage

GB

Clear Storage

function ControlledNumberInput({
  value: initialValue = null,
  ...args
}: ControlledNumberInputProps): React.JSX.Element {
  const [value, setValue] = useState<number | null>(initialValue);

  return (
    <NumberInput
      {...(args as NumberInputProps)}
      onChange={setValue}
      value={value}
    />
  );
}

<ControlledNumberInput {...args} />

Sizes

Small

Medium

Large

function ControlledNumberInput({
  value: initialValue = null,
  ...args
}: ControlledNumberInputProps): React.JSX.Element {
  const [value, setValue] = useState<number | null>(initialValue);

  return (
    <NumberInput
      {...(args as NumberInputProps)}
      onChange={setValue}
      value={value}
    />
  );
}

<div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
  <ControlledNumberInput label="Small" size="sm" value={10} />
  <ControlledNumberInput label="Medium" size="md" value={20} />
  <ControlledNumberInput label="Large" size="lg" value={30} />
</div>

Disabled

Quantity

function ControlledNumberInput({
  value: initialValue = null,
  ...args
}: ControlledNumberInputProps): React.JSX.Element {
  const [value, setValue] = useState<number | null>(initialValue);

  return (
    <NumberInput
      {...(args as NumberInputProps)}
      onChange={setValue}
      value={value}
    />
  );
}

<ControlledNumberInput {...args} />

Status Variants

Error

Value is out of range

Warning

Value is unusually high

Success

Value is valid

function ControlledNumberInput({
  value: initialValue = null,
  ...args
}: ControlledNumberInputProps): React.JSX.Element {
  const [value, setValue] = useState<number | null>(initialValue);

  return (
    <NumberInput
      {...(args as NumberInputProps)}
      onChange={setValue}
      value={value}
    />
  );
}

<div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
  <ControlledNumberInput
    label="Error"
    status={{message: 'Value is out of range', type: 'error'}}
    value={999}
  />
  <ControlledNumberInput
    label="Warning"
    status={{message: 'Value is unusually high', type: 'warning'}}
    value={95}
  />
  <ControlledNumberInput
    label="Success"
    status={{message: 'Value is valid', type: 'success'}}
    value={50}
  />
</div>

Integer Only

Count

function ControlledNumberInput({
  value: initialValue = null,
  ...args
}: ControlledNumberInputProps): React.JSX.Element {
  const [value, setValue] = useState<number | null>(initialValue);

  return (
    <NumberInput
      {...(args as NumberInputProps)}
      onChange={setValue}
      value={value}
    />
  );
}

<ControlledNumberInput {...args} />

Min Max

Percentage

function ControlledNumberInput({
  value: initialValue = null,
  ...args
}: ControlledNumberInputProps): React.JSX.Element {
  const [value, setValue] = useState<number | null>(initialValue);

  return (
    <NumberInput
      {...(args as NumberInputProps)}
      onChange={setValue}
      value={value}
    />
  );
}

<ControlledNumberInput {...args} />

With Start Icon

Number

function ControlledNumberInput({
  value: initialValue = null,
  ...args
}: ControlledNumberInputProps): React.JSX.Element {
  const [value, setValue] = useState<number | null>(initialValue);

  return (
    <NumberInput
      {...(args as NumberInputProps)}
      onChange={setValue}
      value={value}
    />
  );
}

<ControlledNumberInput {...args} />

With Label Icon

Price

function ControlledNumberInput({
  value: initialValue = null,
  ...args
}: ControlledNumberInputProps): React.JSX.Element {
  const [value, setValue] = useState<number | null>(initialValue);

  return (
    <NumberInput
      {...(args as NumberInputProps)}
      onChange={setValue}
      value={value}
    />
  );
}

<ControlledNumberInput {...args} />

Required

Quantity · Required

function ControlledNumberInput({
  value: initialValue = null,
  ...args
}: ControlledNumberInputProps): React.JSX.Element {
  const [value, setValue] = useState<number | null>(initialValue);

  return (
    <NumberInput
      {...(args as NumberInputProps)}
      onChange={setValue}
      value={value}
    />
  );
}

<ControlledNumberInput {...args} />

Optional

Quantity · Optional

function ControlledNumberInput({
  value: initialValue = null,
  ...args
}: ControlledNumberInputProps): React.JSX.Element {
  const [value, setValue] = useState<number | null>(initialValue);

  return (
    <NumberInput
      {...(args as NumberInputProps)}
      onChange={setValue}
      value={value}
    />
  );
}

<ControlledNumberInput {...args} />

With Description

QuantityEnter a value between 1 and 100

function ControlledNumberInput({
  value: initialValue = null,
  ...args
}: ControlledNumberInputProps): React.JSX.Element {
  const [value, setValue] = useState<number | null>(initialValue);

  return (
    <NumberInput
      {...(args as NumberInputProps)}
      onChange={setValue}
      value={value}
    />
  );
}

<ControlledNumberInput {...args} />

With Placeholder

Quantity

function ControlledNumberInput({
  value: initialValue = null,
  ...args
}: ControlledNumberInputProps): React.JSX.Element {
  const [value, setValue] = useState<number | null>(initialValue);

  return (
    <NumberInput
      {...(args as NumberInputProps)}
      onChange={setValue}
      value={value}
    />
  );
}

<ControlledNumberInput {...args} />

With End Content

Price

USD

function ControlledNumberInput({
  value: initialValue = null,
  ...args
}: ControlledNumberInputProps): React.JSX.Element {
  const [value, setValue] = useState<number | null>(initialValue);

  return (
    <NumberInput
      {...(args as NumberInputProps)}
      onChange={setValue}
      value={value}
    />
  );
}

<ControlledNumberInput {...args} />

Loading

Calculating

function ControlledNumberInput({
  value: initialValue = null,
  ...args
}: ControlledNumberInputProps): React.JSX.Element {
  const [value, setValue] = useState<number | null>(initialValue);

  return (
    <NumberInput
      {...(args as NumberInputProps)}
      onChange={setValue}
      value={value}
    />
  );
}

<ControlledNumberInput {...args} />

Read Only

Quantity

function ControlledNumberInput({
  value: initialValue = null,
  ...args
}: ControlledNumberInputProps): React.JSX.Element {
  const [value, setValue] = useState<number | null>(initialValue);

  return (
    <NumberInput
      {...(args as NumberInputProps)}
      onChange={setValue}
      value={value}
    />
  );
}

<ControlledNumberInput {...args} />

API

NumberInput

Numeric input field with optional min/max bounds and step control.

When isOptional: false, isRequired: false, hasClear: true

Prop	Type	Default	Description
autoComplete	string	—	HTML autocomplete attribute value.
className	string	—	Additional CSS class names applied to the field root, or to the input wrapper when the input is inside an InputGroup.
data-testid	string	—	Test ID applied to the input element.
description	ReactNode	—	Supporting text displayed below the label.
endContent	ReactNode	—	Content rendered after the input, before the status icon.
hasAutoFocus	boolean	false	Whether to focus the input on mount.
htmlName	string	—	HTML name attribute.
isDisabled	boolean	false	Whether the input is disabled.
isReadOnly	boolean	false	Whether the value is displayed without allowing focus or interaction.
isIntegerOnly	boolean	false	Whether to restrict input to integer values only.
isWheelEnabled	boolean	false	Whether scrolling the mouse wheel over the focused input changes its value.
isLabelHidden	boolean	false	Whether to visually hide the label.
isLoading	boolean	false	Whether the input is in a loading state.
label*	string	—	Field label.
labelEnd	ReactNode	—	Content shown at the end of the label row, such as a link. It renders outside the label, so it does not focus the control or change its accessible name. It stays visible when isLabelHidden is true.
labelIcon	IconComponent	—	Icon rendered beside the label.
labelTooltip	ReactNode	—	Tooltip content shown next to the label.
max	number | null	—	Maximum allowed value.
min	number | null	—	Minimum allowed value.
onBlur	(event: FocusEvent<HTMLInputElement>) => void	—	Called when the input loses focus.
onEnter	() => void	—	Called when Enter is pressed.
onFocus	(event: FocusEvent<HTMLInputElement>) => void	—	Called when the input receives focus.
onKeyDown	(event: KeyboardEvent<HTMLInputElement>) => void	—	Keyboard event handler for the input.
placeholder	string	—	Placeholder text.
ref	Ref<HTMLInputElement>	—	Ref forwarded to the input element.
size	"sm" | "md" | "lg"	'md'	Visual size.
startIcon	IconComponent	—	Icon shown before the input.
status	InputStatus	—	Validation status displayed below the input.
step	number | null	—	Step increment for the number input.
style	CSSProperties	—	Inline styles applied to the field root, or to the input wrapper when the input is inside an InputGroup.
units	string | null	—	Unit label displayed after the input value.
value*	number | null	—	Controlled numeric value.
isOptional	false	—
isRequired	false	—
hasClear*	true	—	Whether to show a clear button.
onChange*	(value: number | null) => void	—	Called when the numeric value changes or is cleared.

When isOptional: true, isRequired: false, hasClear: true

Prop	Type	Default	Description
autoComplete	string	—	HTML autocomplete attribute value.
className	string	—	Additional CSS class names applied to the field root, or to the input wrapper when the input is inside an InputGroup.
data-testid	string	—	Test ID applied to the input element.
description	ReactNode	—	Supporting text displayed below the label.
endContent	ReactNode	—	Content rendered after the input, before the status icon.
hasAutoFocus	boolean	false	Whether to focus the input on mount.
htmlName	string	—	HTML name attribute.
isDisabled	boolean	false	Whether the input is disabled.
isReadOnly	boolean	false	Whether the value is displayed without allowing focus or interaction.
isIntegerOnly	boolean	false	Whether to restrict input to integer values only.
isWheelEnabled	boolean	false	Whether scrolling the mouse wheel over the focused input changes its value.
isLabelHidden	boolean	false	Whether to visually hide the label.
isLoading	boolean	false	Whether the input is in a loading state.
label*	string	—	Field label.
labelEnd	ReactNode	—	Content shown at the end of the label row, such as a link. It renders outside the label, so it does not focus the control or change its accessible name. It stays visible when isLabelHidden is true.
labelIcon	IconComponent	—	Icon rendered beside the label.
labelTooltip	ReactNode	—	Tooltip content shown next to the label.
max	number | null	—	Maximum allowed value.
min	number | null	—	Minimum allowed value.
onBlur	(event: FocusEvent<HTMLInputElement>) => void	—	Called when the input loses focus.
onEnter	() => void	—	Called when Enter is pressed.
onFocus	(event: FocusEvent<HTMLInputElement>) => void	—	Called when the input receives focus.
onKeyDown	(event: KeyboardEvent<HTMLInputElement>) => void	—	Keyboard event handler for the input.
placeholder	string	—	Placeholder text.
ref	Ref<HTMLInputElement>	—	Ref forwarded to the input element.
size	"sm" | "md" | "lg"	'md'	Visual size.
startIcon	IconComponent	—	Icon shown before the input.
status	InputStatus	—	Validation status displayed below the input.
step	number | null	—	Step increment for the number input.
style	CSSProperties	—	Inline styles applied to the field root, or to the input wrapper when the input is inside an InputGroup.
units	string | null	—	Unit label displayed after the input value.
value*	number | null	—	Controlled numeric value.
isOptional*	true	—
isRequired	false	—
hasClear*	true	—	Whether to show a clear button.
onChange*	(value: number | null) => void	—	Called when the numeric value changes or is cleared.

When isOptional: false, isRequired: true, hasClear: true

Prop	Type	Default	Description
autoComplete	string	—	HTML autocomplete attribute value.
className	string	—	Additional CSS class names applied to the field root, or to the input wrapper when the input is inside an InputGroup.
data-testid	string	—	Test ID applied to the input element.
description	ReactNode	—	Supporting text displayed below the label.
endContent	ReactNode	—	Content rendered after the input, before the status icon.
hasAutoFocus	boolean	false	Whether to focus the input on mount.
htmlName	string	—	HTML name attribute.
isDisabled	boolean	false	Whether the input is disabled.
isReadOnly	boolean	false	Whether the value is displayed without allowing focus or interaction.
isIntegerOnly	boolean	false	Whether to restrict input to integer values only.
isWheelEnabled	boolean	false	Whether scrolling the mouse wheel over the focused input changes its value.
isLabelHidden	boolean	false	Whether to visually hide the label.
isLoading	boolean	false	Whether the input is in a loading state.
label*	string	—	Field label.
labelEnd	ReactNode	—	Content shown at the end of the label row, such as a link. It renders outside the label, so it does not focus the control or change its accessible name. It stays visible when isLabelHidden is true.
labelIcon	IconComponent	—	Icon rendered beside the label.
labelTooltip	ReactNode	—	Tooltip content shown next to the label.
max	number | null	—	Maximum allowed value.
min	number | null	—	Minimum allowed value.
onBlur	(event: FocusEvent<HTMLInputElement>) => void	—	Called when the input loses focus.
onEnter	() => void	—	Called when Enter is pressed.
onFocus	(event: FocusEvent<HTMLInputElement>) => void	—	Called when the input receives focus.
onKeyDown	(event: KeyboardEvent<HTMLInputElement>) => void	—	Keyboard event handler for the input.
placeholder	string	—	Placeholder text.
ref	Ref<HTMLInputElement>	—	Ref forwarded to the input element.
size	"sm" | "md" | "lg"	'md'	Visual size.
startIcon	IconComponent	—	Icon shown before the input.
status	InputStatus	—	Validation status displayed below the input.
step	number | null	—	Step increment for the number input.
style	CSSProperties	—	Inline styles applied to the field root, or to the input wrapper when the input is inside an InputGroup.
units	string | null	—	Unit label displayed after the input value.
value*	number | null	—	Controlled numeric value.
isOptional	false	—
isRequired*	true	—
hasClear*	true	—	Whether to show a clear button.
onChange*	(value: number | null) => void	—	Called when the numeric value changes or is cleared.

When isOptional: false, isRequired: false, hasClear: false

Prop	Type	Default	Description
autoComplete	string	—	HTML autocomplete attribute value.
className	string	—	Additional CSS class names applied to the field root, or to the input wrapper when the input is inside an InputGroup.
data-testid	string	—	Test ID applied to the input element.
description	ReactNode	—	Supporting text displayed below the label.
endContent	ReactNode	—	Content rendered after the input, before the status icon.
hasAutoFocus	boolean	false	Whether to focus the input on mount.
htmlName	string	—	HTML name attribute.
isDisabled	boolean	false	Whether the input is disabled.
isReadOnly	boolean	false	Whether the value is displayed without allowing focus or interaction.
isIntegerOnly	boolean	false	Whether to restrict input to integer values only.
isWheelEnabled	boolean	false	Whether scrolling the mouse wheel over the focused input changes its value.
isLabelHidden	boolean	false	Whether to visually hide the label.
isLoading	boolean	false	Whether the input is in a loading state.
label*	string	—	Field label.
labelEnd	ReactNode	—	Content shown at the end of the label row, such as a link. It renders outside the label, so it does not focus the control or change its accessible name. It stays visible when isLabelHidden is true.
labelIcon	IconComponent	—	Icon rendered beside the label.
labelTooltip	ReactNode	—	Tooltip content shown next to the label.
max	number | null	—	Maximum allowed value.
min	number | null	—	Minimum allowed value.
onBlur	(event: FocusEvent<HTMLInputElement>) => void	—	Called when the input loses focus.
onEnter	() => void	—	Called when Enter is pressed.
onFocus	(event: FocusEvent<HTMLInputElement>) => void	—	Called when the input receives focus.
onKeyDown	(event: KeyboardEvent<HTMLInputElement>) => void	—	Keyboard event handler for the input.
placeholder	string	—	Placeholder text.
ref	Ref<HTMLInputElement>	—	Ref forwarded to the input element.
size	"sm" | "md" | "lg"	'md'	Visual size.
startIcon	IconComponent	—	Icon shown before the input.
status	InputStatus	—	Validation status displayed below the input.
step	number | null	—	Step increment for the number input.
style	CSSProperties	—	Inline styles applied to the field root, or to the input wrapper when the input is inside an InputGroup.
units	string | null	—	Unit label displayed after the input value.
value*	number | null	—	Controlled numeric value.
isOptional	false	—
isRequired	false	—
hasClear	false	—	Whether to show a clear button.
onChange*	(value: number) => void	—	Called when the numeric value changes.

When isOptional: true, isRequired: false, hasClear: false

Prop	Type	Default	Description
autoComplete	string	—	HTML autocomplete attribute value.
className	string	—	Additional CSS class names applied to the field root, or to the input wrapper when the input is inside an InputGroup.
data-testid	string	—	Test ID applied to the input element.
description	ReactNode	—	Supporting text displayed below the label.
endContent	ReactNode	—	Content rendered after the input, before the status icon.
hasAutoFocus	boolean	false	Whether to focus the input on mount.
htmlName	string	—	HTML name attribute.
isDisabled	boolean	false	Whether the input is disabled.
isReadOnly	boolean	false	Whether the value is displayed without allowing focus or interaction.
isIntegerOnly	boolean	false	Whether to restrict input to integer values only.
isWheelEnabled	boolean	false	Whether scrolling the mouse wheel over the focused input changes its value.
isLabelHidden	boolean	false	Whether to visually hide the label.
isLoading	boolean	false	Whether the input is in a loading state.
label*	string	—	Field label.
labelEnd	ReactNode	—	Content shown at the end of the label row, such as a link. It renders outside the label, so it does not focus the control or change its accessible name. It stays visible when isLabelHidden is true.
labelIcon	IconComponent	—	Icon rendered beside the label.
labelTooltip	ReactNode	—	Tooltip content shown next to the label.
max	number | null	—	Maximum allowed value.
min	number | null	—	Minimum allowed value.
onBlur	(event: FocusEvent<HTMLInputElement>) => void	—	Called when the input loses focus.
onEnter	() => void	—	Called when Enter is pressed.
onFocus	(event: FocusEvent<HTMLInputElement>) => void	—	Called when the input receives focus.
onKeyDown	(event: KeyboardEvent<HTMLInputElement>) => void	—	Keyboard event handler for the input.
placeholder	string	—	Placeholder text.
ref	Ref<HTMLInputElement>	—	Ref forwarded to the input element.
size	"sm" | "md" | "lg"	'md'	Visual size.
startIcon	IconComponent	—	Icon shown before the input.
status	InputStatus	—	Validation status displayed below the input.
step	number | null	—	Step increment for the number input.
style	CSSProperties	—	Inline styles applied to the field root, or to the input wrapper when the input is inside an InputGroup.
units	string | null	—	Unit label displayed after the input value.
value*	number | null	—	Controlled numeric value.
isOptional*	true	—
isRequired	false	—
hasClear	false	—	Whether to show a clear button.
onChange*	(value: number) => void	—	Called when the numeric value changes.

When isOptional: false, isRequired: true, hasClear: false

Prop	Type	Default	Description
autoComplete	string	—	HTML autocomplete attribute value.
className	string	—	Additional CSS class names applied to the field root, or to the input wrapper when the input is inside an InputGroup.
data-testid	string	—	Test ID applied to the input element.
description	ReactNode	—	Supporting text displayed below the label.
endContent	ReactNode	—	Content rendered after the input, before the status icon.
hasAutoFocus	boolean	false	Whether to focus the input on mount.
htmlName	string	—	HTML name attribute.
isDisabled	boolean	false	Whether the input is disabled.
isReadOnly	boolean	false	Whether the value is displayed without allowing focus or interaction.
isIntegerOnly	boolean	false	Whether to restrict input to integer values only.
isWheelEnabled	boolean	false	Whether scrolling the mouse wheel over the focused input changes its value.
isLabelHidden	boolean	false	Whether to visually hide the label.
isLoading	boolean	false	Whether the input is in a loading state.
label*	string	—	Field label.
labelEnd	ReactNode	—	Content shown at the end of the label row, such as a link. It renders outside the label, so it does not focus the control or change its accessible name. It stays visible when isLabelHidden is true.
labelIcon	IconComponent	—	Icon rendered beside the label.
labelTooltip	ReactNode	—	Tooltip content shown next to the label.
max	number | null	—	Maximum allowed value.
min	number | null	—	Minimum allowed value.
onBlur	(event: FocusEvent<HTMLInputElement>) => void	—	Called when the input loses focus.
onEnter	() => void	—	Called when Enter is pressed.
onFocus	(event: FocusEvent<HTMLInputElement>) => void	—	Called when the input receives focus.
onKeyDown	(event: KeyboardEvent<HTMLInputElement>) => void	—	Keyboard event handler for the input.
placeholder	string	—	Placeholder text.
ref	Ref<HTMLInputElement>	—	Ref forwarded to the input element.
size	"sm" | "md" | "lg"	'md'	Visual size.
startIcon	IconComponent	—	Icon shown before the input.
status	InputStatus	—	Validation status displayed below the input.
step	number | null	—	Step increment for the number input.
style	CSSProperties	—	Inline styles applied to the field root, or to the input wrapper when the input is inside an InputGroup.
units	string | null	—	Unit label displayed after the input value.
value*	number | null	—	Controlled numeric value.
isOptional	false	—
isRequired*	true	—
hasClear	false	—	Whether to show a clear button.
onChange*	(value: number) => void	—	Called when the numeric value changes.