NumberInput

Capture number input from user

Import

Source

View source code

Docs

Edit this page

Package

@asuikit/core

Usage

Your age

Placeholder

Label

Description

Error

Variant

Radius

Size

Disabled

With asterisk

Hide controls

import { NumberInput } from '@asuikit/core';

function Demo() {
  return (
    <NumberInput
      defaultValue={18}
      placeholder="Your age"
      label="Your age"
      withAsterisk
    />
  );
}

Controlled

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

function Demo() {
  const [value, setValue] = useState<number | ''>(0);
  return <NumberInput value={value} onChange={setValue} />;
}

NumberInput value type number | '' (number or empty string). Empty string indicates that the input is empty. number | '' type is used in all props that contain value: value, defaultValue, onChange.

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:

<NumberInput noClampOnBlur />

Parser and formatter

With parser and formatter props you can customize how value is displayed in the input:

Price

import { NumberInput } from '@asuikit/core';

function Demo() {
  return (
    <NumberInput
      label="Price"
      defaultValue={1000}
      parser={(value) => value.replace(/\$\s?|(,*)/g, '')}
      formatter={(value) =>
        !Number.isNaN(parseFloat(value))
          ? `$ ${value}`.replace(/\B(?<!\.\d*)(?=(\d{3})+(?!\d))/g, ',')
          : '$ '
      }
    />
  );
}

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:

Your age

From 0 to 120, step is 1

Your weight in kg

From 0 to Infinity, step is 5

import { NumberInput } from '@asuikit/core';

function Demo() {
  return (
    <>
      <NumberInput
        label="Your age"
        description="From 0 to 120, step is 1"
        placeholder="Your age"
        max={120}
        min={0}
      />

      <NumberInput
        label="Your weight in kg"
        description="From 0 to Infinity, step is 5"
        defaultValue={80}
        step={5}
        min={0}
      />
    </>
  );
}

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:

Step on hold

Step the value when clicking and holding the arrows

Step the value with interval function

Step value will increase incrementally when control is hold

import { NumberInput } from '@asuikit/core';

function Demo() {
  return (
    <>
      <NumberInput
        label="Step on hold"
        description="Step the value when clicking and holding the arrows"
        stepHoldDelay={500}
        stepHoldInterval={100}
      />

      <NumberInput
        label="Step the value with interval function"
        description="Step value will increase incrementally when control is hold"
        stepHoldDelay={500}
        stepHoldInterval={(t) => Math.max(1000 / t ** 2, 25)}
      />
    </>
  );
}

Decimal steps

To use decimal steps set following props:

step – decimal number, e.g. 0.05
precision – amount of significant digits

Number input with decimal steps

import { NumberInput } from '@asuikit/core';

function Demo() {
  return (
    <NumberInput
      label="Number input with decimal steps"
      defaultValue={0.05}
      precision={2}
      min={-1}
      step={0.05}
      max={1}
    />
  );
}

Decimal/Thousands separator

To change the separators set decimalSeparator and thousandsSeparator props:

Number input with custom separators

import { NumberInput } from '@asuikit/core';

function Demo() {
  return (
    <NumberInput
      decimalSeparator=","
      thousandsSeparator="."
      label="Number input with custom separators"
      defaultValue={0.5}
      precision={2}
      step={0.5}
    />
  );
}

Remove controls

Controls are not rendered in these cases:

hideControls prop is set to true
Input is disabled
variant prop is set to unstyled

By default controls are visible

Disable them with hideControls prop

Controls also not rendered when input is disabled

import { NumberInput } from '@asuikit/core';

function Demo() {
  return (
    <>
      <NumberInput label="By default controls are visible" />

      <NumberInput
        hideControls
        label="Disable them with hideControls prop"
      />

      <NumberInput
        label="Disabled"
        disabled
        label="Controls also not rendered when input is disabled"
      />
    </>
  );
}

Custom increment/decrement controls

NumberInput exposes increment/decrement functions with handlersRef prop. You can use it to create custom controls:

import { useState, useRef } from 'react';
import { NumberInput, Group, ActionIcon, NumberInputHandlers, rem } from '@asuikit/core';

function Demo() {
  const [value, setValue] = useState<number | ''>(0);
  const handlers = useRef<NumberInputHandlers>();

  return (
    <Group spacing={5}>
      <ActionIcon size={42} variant="default" onClick={() => handlers.current.decrement()}>
        –
      </ActionIcon>

      <NumberInput
        hideControls
        value={value}
        onChange={(val) => setValue(val)}
        handlersRef={handlers}
        max={10}
        min={0}
        step={2}
        styles={{ input: { width: rem(54), textAlign: 'center' } }}
      />

      <ActionIcon size={42} variant="default" onClick={() => handlers.current.increment()}>
        +
      </ActionIcon>
    </Group>
  );
}

Invalid state and error

Your age

You must be at least 21

// Error as boolean – red border color
<NumberInput error />

// Error as React node – red border color and message below input
<NumberInput error="You must be at least 21" />

Disabled state

Controls to increment/decrement value are not displayed when input is disabled:

Disabled

import { NumberInput } from '@asuikit/core';

function Demo() {
  return <NumberInput disabled />;
}

With icon

Age when you graduated

import { NumberInput } from '@asuikit/core';
import { IconMedal } from '@tabler/icons-react';

function Demo() {
  return (
    <NumberInput
      label="Age when you graduated"
      placeholder="Age when you graduated"
      defaultValue={22}
      min={0}
      max={120}
      icon={<IconMedal size="1rem" />}
    />
  );
}

Get input ref

import { useRef } from 'react';
import { NumberInput } from '@asuikit/core';

function Demo() {
  const ref = useRef<HTMLInputElement>(null);
  return <NumberInput ref={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 /> // -> not ok, input is not labeled
<NumberInput label="Your age" /> // -> ok, input and label is connected
<NumberInput aria-label="Your age" /> // -> ok, label is not visible but will be announced by screen reader

Go back

NativeSelect – @asuikit/core

Up next

PasswordInput – @asuikit/core

NumberInput component props

Name	Type	Description
decimalSeparator	string	The decimal separator
defaultValue	number \| ""	Default value for uncontrolled component
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
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	Called when value changes
parser	Parser	Parses the value from formatter, should be used with formatter at the same time
placeholder	string
precision	number	Amount of digits after the decimal point
radius	number \| "xs" \| "sm" \| "md" \| "lg" \| "xl"	Key of theme.radius or any valid CSS value to set border-radius, theme.defaultRadius by default
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.
thousandsSeparator	string	The thousands separator
type	"number" \| "text"	Input type, defaults to text
value	number \| ""	Input value for controlled component
variant	Variants<"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	.asuikit-NumberInput-wrapper	Root Input element
icon	.asuikit-NumberInput-icon	Input icon wrapper on the left side of the input, controlled by icon prop
input	.asuikit-NumberInput-input	Main input element
rightSection	.asuikit-NumberInput-rightSection	Right section with up and down controls
root	.asuikit-NumberInput-root	Root element
label	.asuikit-NumberInput-label	Label element styles, defined by label prop
error	.asuikit-NumberInput-error	Error element styles, defined by error prop
description	.asuikit-NumberInput-description	Description element styles, defined by description prop
required	.asuikit-NumberInput-required	Required asterisk element styles, defined by required prop
control	.asuikit-NumberInput-control	Shared up and down controls styles
controlUp	.asuikit-NumberInput-controlUp	Up control styles
controlDown	.asuikit-NumberInput-controlDown	Down control styles

Learn more about Styles API

Build fully functional accessible web applications faster than ever

About

Contribute About Mantine Changelog Releases

Community

Chat on Discord Follow on Twitter Follow on GitHub GitHub discussions

Project

Mantine UI Documentation GitHub organization npm organization

Built by Vitaly Rtishchev and these awesome people

Join Discord community

Follow Mantine on Twitter