NumberInput
Usage
Controlled
Clamp on blur
Component has internal state to manage user input, when blur event is triggered
internal value is clamped with given min and max values and onChange
handler is called with result.
For example, if you put 123
or -20
in age input in next example, values will be clamped on blur: 123 -> 120
, -20 -> 0
.
If you want to disable this behavior set noClampOnBlur
prop:
Parser and formatter
With parser
and formatter
props you can customize how value is displayed in the input:
Min, max and step
Min and max values define upper and lower value which may be entered. When user clicks controls or presses up/down arrows, value is incremented/decremented by step:
Increment/decrement on hold
Set stepHoldDelay
and stepHoldInterval
props to define behavior when increment/decrement controls are clicked and hold,
this will also overwrite default up and down arrows behavior:
Decimal steps
To use decimal steps set following props:
step
– decimal number, e.g.0.05
precision
– amount of significant digits
Decimal separator
To change decimal separator set decimalSeparator
prop:
Remove controls
Controls are not rendered in these cases:
hideControls
prop is set to true- Input is disabled
variant
prop is set to unstyled
Custom increment/decrement controls
NumberInput exposes increment/decrement functions with handlersRef
prop.
You can use it to create custom controls:
Invalid state and error
Disabled state
Controls to increment/decrement value are not displayed when input is disabled:
With icon
Get input ref
Accessibility
NumberInput renders regular input with type="text"
.
Increment/decrement controls have aria-hidden
attribute and cannot be focused
– users with keyboard can increment/decrement value by step with up/down arrows.
Provide aria-label
in case you use component without label for screen reader support:
NumberInput component props
Name | Type | Description |
---|---|---|
decimalSeparator | string | The decimal separator |
defaultValue | number | Default value for uncontrolled variant only |
description | ReactNode | Input description, displayed after label |
descriptionProps | Record<string, any> | Props spread to description element |
disabled | boolean | Disabled input state |
error | ReactNode | Displays error message after input |
errorProps | Record<string, any> | Props spread to error element |
formatter | Formatter | Formats the number into the input |
handlersRef | ForwardedRef<NumberInputHandlers> | Get increment/decrement handlers |
hideControls | boolean | Removes increment/decrement controls |
icon | ReactNode | Adds icon on the left side of input |
iconWidth | Width<string | number> | Width of icon section in px |
inputContainer | (children: ReactNode) => ReactNode | Input container component, defaults to React.Fragment |
inputWrapperOrder | ("input" | "label" | "error" | "description")[] | Controls order of the Input.Wrapper elements |
label | ReactNode | Input label, displayed before input |
labelProps | Record<string, any> | Props spread to label element |
max | number | Maximum possible value |
min | number | Minimal possible value |
noClampOnBlur | boolean | Prevent value clamp on blur |
onChange | (value: number) => void | onChange input handler for controlled variant, note that input event is not exposed. It will return undefined if the input is empty, otherwise it'll return a number |
parser | Parser | Parses the value from formatter, should be used with formatter at the same time |
precision | number | Amount of digits after the decimal point |
radius | number | "xs" | "sm" | "md" | "lg" | "xl" | Input border-radius from theme or number to set border-radius in px |
removeTrailingZeros | boolean | Only works if a precision is given, removes the trailing zeros, false by default |
required | boolean | Sets required on input element |
rightSection | ReactNode | Right section of input, similar to icon but on the right |
rightSectionProps | Record<string, any> | Props spread to rightSection div element |
rightSectionWidth | Width<string | number> | Width of right section, is used to calculate input padding-right |
size | "xs" | "sm" | "md" | "lg" | "xl" | Input size |
startValue | number | First value if no initial value was set and increment/decrement is triggered using controls or up/down arrows |
step | number | Number by which value will be incremented/decremented with controls and up/down arrows |
stepHoldDelay | number | Initial delay in milliseconds before stepping the value. |
stepHoldInterval | number | ((stepCount: number) => number) | Delay before stepping the value. Can be a number of milliseconds or a function that receives the current step count and returns the delay in milliseconds. |
type | "number" | "text" | Input type, defaults to text |
value | number | Input value for controlled variant |
variant | "unstyled" | "default" | "filled" | Defines input appearance, defaults to default in light color scheme and filled in dark |
withAsterisk | boolean | Determines whether required asterisk should be rendered, overrides required prop, does not add required attribute to the input |
wrapperProps | Record<string, any> | Props passed to root element (InputWrapper component) |
NumberInput component Styles API
Name | Static selector | Description |
---|---|---|
wrapper | .mantine-NumberInput-wrapper | Root Input element |
invalid | .mantine-NumberInput-invalid | Invalid input modifier |
disabled | .mantine-NumberInput-disabled | Invalid disabled modifier |
icon | .mantine-NumberInput-icon | Input icon wrapper on the left side of the input, controlled by icon prop |
withIcon | .mantine-NumberInput-withIcon | Input element styles when used with icon, controlled by icon prop |
input | .mantine-NumberInput-input | Main input element |
rightSection | .mantine-NumberInput-rightSection | Right section with up and down controls |
root | .mantine-NumberInput-root | Root element |
label | .mantine-NumberInput-label | Label element styles, defined by label prop |
error | .mantine-NumberInput-error | Error element styles, defined by error prop |
description | .mantine-NumberInput-description | Description element styles, defined by description prop |
required | .mantine-NumberInput-required | Required asterisk element styles, defined by required prop |
control | .mantine-NumberInput-control | Shared up and down controls styles |
controlUp | .mantine-NumberInput-controlUp | Up control styles |
controlDown | .mantine-NumberInput-controlDown | Down control styles |