NumberInput

The NumberInput component allows users to input numbers.

Basic usage

You can use the defaultValue prop to set the initial value, and access this from value on the component state.

Ranges and step size

You can set the min, max, and step of the number input. Note that precision also needs to be set for fractional steps.

Formats

The format prop can be set to "currency" or "percent".

Component API

NameDescriptionDefault
id
string
The ID referenced by the global component state.
defaultValue
number
The input value on initial render.
defaultDisabled
boolean
The input's disabled state on initial render.
validate
((value: number) => number | undefined) | Array<(value: number) => number | undefined>
A single function or an array of functions that validate the input value.
required
boolean
Adds red asterisk on the right side of label and sets required on input element
false
onChange
(value: number) => void
Callback when input changes when using as a controlled component. Prefer using the global component state.
variant
"unstyled" | "default"
Input appearance.
size
"xs" | "sm" | "md" | "lg" | "xl"
Input size.
disabled
boolean
Disables the input. Prefer to use defaultDisabled and component state.
radius
"xs" | "sm" | "md" | "lg" | "xl"
The input's border radius.
sx
CSSObject
CSS style overrides.
width
number | "content" | "auto" | `${number}%` | `${number}/${number}` | { xs?: ColWidth; sm?: ColWidth; md?: ColWidth; lg?: ColWidth; xl?: ColWidth; }
Width of the component. This component must be a direct child of a <Stack> for this prop to take effect. If an integer is specified, signifies the width in a 12 item grid. 12 means that the component takes up the entire row, 6 is half, 1 is 1/12. If a decimal or fraction is specified, signifies the fractional share of the row. e.g. 1/2 takes up half of the row. If a percentage is specified, signifies the percentage share of the row. e.g. "50%" takes up half of the row. content indicates that the component should take up as much space as its content. auto indicates that the component should take any leftover space on the row. To set width based on the screen size, use an object with a specific width for each breakpoint. e.g. {xs: "100%", md: "50%"} sets the width on xs-md screens to 100% and md and larger screens to 50%.
content
offset
number | `${number}%` | `${number}/${number}` | { xs?: ColOffset; sm?: ColOffset; md?: ColOffset; lg?: ColOffset; xl?: ColOffset; }
Creates a gap to the left of the component. Has the same units as width. This component must be a direct child of a <Stack> for this prop to take effect. If an integer is specified, signifies the offset in a 12 item grid. 6 means the component is offset by half a row, 1 is 1/12 of a row. If a decimal or fraction is specified, signifies the fractional share of the row. e.g. 1/2 offsets a component by half of the row. If a percentage is specified, signifies the percentage share of the row. e.g. "50%" offsets a component by half of the row. To set offset based on the screen size, use an object with a specific offset for each breakpoint. e.g. {xs: "50%", md: "0%"} sets the offset on xs-md screens to 50% and md and larger screens to 0%.
value
number
The value of the input when using as a controlled component. Prefer using defaultValue and the global component state.
step
number
Number by which value will be incremented/decremented with controls and up/down arrows. Specify `precision` if using a non-integer step.
error
Component
Error text displayed below the input.
label
Component
Label displayed above the input.
description
Component
Description displayed below the input.
max
number
Maximum possible value. Inputs are clamped to this maximum.
min
number
Minimum possible value. Inputs are clamped to this minimum.
icon
Component
Adds an icon to the left of the input.
format
"decimal" | "currency" | "percent"
The formatting style to use.
decimal
currency
"AUD" | "CAD" | "CLP" | "CNY" | "COP" | "GBP" | "HKD" | "INR" | "JPY" | "KRW" | "MYR" | "MXN" | "NZD" | "NOK" | "PHP" | "SGD" | "TWD" | "USD" | "ZAR" | "ARS" | "BRL" | "CHF" | "DKK" | "EUR" | "ILS" | "PLN"
A three letter currency code to use, such as GBP, if `format` is set to `currency`.
USD
precision
number
Number of digits after the decimal point.
removeTrailingZeros
boolean
If `precision` is set, removes the trailing zeros.
false
hideControls
boolean
Removes increment/decrement controls.

State API

NameDescription
value
number
The number currently in the number input
setValue
(value: number) => void
Sets the value of the number input
disabled
boolean
Whether the number input is disabled
setDisabled
(disabled?: boolean) => void
Sets the disabled value of the number input. If the `disabled` value is not provided, the number input will be disabled