NumberField

NumberField allows for numerical input.

Props

Component props
Name	Type	Default
`id` Required	`string`	-
	A unique identifier for the input.
`onChange` Required	`({\| event: SyntheticInputEvent<HTMLInputElement>, value: number \| void, \|}) => void`	-
	Callback triggered when the value of the input changes, whether by keyboard entry or the input's arrows.
`autoComplete`	`"on" \| "off"`	-
	Indicate if autocomplete should be available on the input.
`disabled`	`boolean`	`false`
	Indicate if the input is disabled.
`errorMessage`	`React.Node`	-
	For most use cases, pass a string with a helpful error message (be sure to localize!). In certain instances it can be useful to make some text clickable; to support this, you may instead pass a React.Node to wrap text in Link or TapArea.
`helperText`	`string`	-
	More information for the user about how to complete the form field.
`label`	`string`	-
	The label for the input. Be sure to localize the text.
`max`	`number`	-
	The upper bound of valid input, inclusive.
`min`	`number`	-
	The lower bound of valid input, inclusive.
`name`	`string`	-
	A unique name for the input.
`onBlur`	`({\| event: SyntheticFocusEvent<HTMLInputElement>, value: number \| void, \|}) => void`	-
	Callback triggered when the user blurs the input.
`onFocus`	`({\| event: SyntheticFocusEvent<HTMLInputElement>, value: number \| void, \|}) => void`	-
	Callback triggered when the user focuses the input.
`onKeyDown`	`({\| event: SyntheticKeyboardEvent<HTMLInputElement>, value: number \| void, \|}) => void`	-
	Callback triggered when the user presses any key while the input is focused.
`placeholder`	`string`	-
	Placeholder text shown the the user has not yet input a value.
`size`	`"md" \| "lg"`	`"md"`
	md: 40px, lg: 48px
`step`	`number`	-
	Indicates the amount the value will increase or decrease when using the input's arrows.
`value`	`number \| void`	-
	The current value of the input.

Usage guidelines

When to Use

Any time succinct numerical data needs to be entered by a user.

When Not to Use

Situations where text needs to be entered. Use TextField or TextArea instead.

Example

NumberField will expand to fill the width of the parent container.

Enter your favorite number

function Example(props) {
  const [value, setValue] = React.useState('')

  return (
    <NumberField
      id="basicExampleNumberField"
      label="Enter your favorite number"
      onChange={({ value }) => {
        setValue(value);
      }}
      placeholder="We recommend 42"
      value={value}
    />
  );
}

function Example(props) {
  const [value, setValue] = React.useState('')
  return (
    <NumberField
      id="basicExampleNumberField"
      label="Enter your favorite number"
      onChange={({ value }) => {
        setValue(value);
      }}
      placeholder="We recommend 42"
      value={value}
    />
  );
}

Example: Disabled

Disabled

function Example(props) {
  const [value, setValue] = React.useState('')

  return (
    <NumberField
      disabled
      id="disabledNumberField"
      label="Disabled"
      onChange={({ value }) => setValue(value)}
      placeholder="This input is disabled"
      value={value}
    />
  );
}

function Example(props) {
  const [value, setValue] = React.useState('')
  return (
    <NumberField
      disabled
      id="disabledNumberField"
      label="Disabled"
      onChange={({ value }) => setValue(value)}
      placeholder="This input is disabled"
      value={value}
    />
  );
}

Example: Helper Text

Whenever you want to provide more information about a form field, you should use helperText.

Phone number

Digits only please, e.g. 8675309

function Example(props) {
  const [value, setValue] = React.useState('')

  return (
    <Box padding={2} color="white">
      <NumberField
        id="helperTextNumberField"
        helperText="Digits only please, e.g. 8675309"
        label="Phone number"
        onChange={({ value }) => setValue(value)}
        value={value}
      />
    </Box>
  );
}

function Example(props) {
  const [value, setValue] = React.useState('')
  return (
    <Box padding={2} color="white">
      <NumberField
        id="helperTextNumberField"
        helperText="Digits only please, e.g. 8675309"
        label="Phone number"
        onChange={({ value }) => setValue(value)}
        value={value}
      />
    </Box>
  );
}

Example: Error message

NumberField can display an error message.
Simply pass in an errorMessage when there is an error present and we will handle the rest.

With an error message

This field can't be blank!

function Example(props) {
  const [value, setValue] = React.useState('')

  return (
    <NumberField
      id="errorMessageNumberField"
      errorMessage={!value ? "This field can't be blank!" : null}
      onChange={({ value }) => setValue(value)}
      label="With an error message"
      value={value}
    />
  );
}

function Example(props) {
  const [value, setValue] = React.useState('')
  return (
    <NumberField
      id="errorMessageNumberField"
      errorMessage={!value ? "This field can't be blank!" : null}
      onChange={({ value }) => setValue(value)}
      label="With an error message"
      value={value}
    />
  );
}

Example: min/max/step

NumberField provides additional props specific to numerical input.

min and max can be used to define the acceptable bounds of the input (see the ref example for more about using these for validation).

step determines the amount incremented or decremented when using the input's arrow buttons. Set this as a float to allow decimal input.

Stepping in intervals of 5

Stepping in intervals of 0.1

function Example(props) {
  const [value1, setValue1] = React.useState('');
  const [value2, setValue2] = React.useState('');

  return (
    <Flex direction="column" gap={2}>
      <NumberField
        id="minMaxStepExampleNumberField1"
        label="Stepping in intervals of 5"
        max={25}
        min={5}
        onChange={({ value }) => {
          setValue1(value);
        }}
        placeholder="Use the arrow buttons to increase/decrease the input value"
        step={5}
        value={value1}
      />
      <NumberField
        id="minMaxStepExampleNumberField2"
        label="Stepping in intervals of 0.1"
        max={2}
        min={-2}
        onChange={({ value }) => {
          setValue2(value);
        }}
        placeholder="Use the arrow buttons to increase/decrease the input value"
        step={0.1}
        value={value2}
      />
    </Flex>
  );
}

function Example(props) {
  const [value1, setValue1] = React.useState('');
  const [value2, setValue2] = React.useState('');
  return (
    <Flex direction="column" gap={2}>
      <NumberField
        id="minMaxStepExampleNumberField1"
        label="Stepping in intervals of 5"
        max={25}
        min={5}
        onChange={({ value }) => {
          setValue1(value);
        }}
        placeholder="Use the arrow buttons to increase/decrease the input value"
        step={5}
        value={value1}
      />
      <NumberField
        id="minMaxStepExampleNumberField2"
        label="Stepping in intervals of 0.1"
        max={2}
        min={-2}
        onChange={({ value }) => {
          setValue2(value);
        }}
        placeholder="Use the arrow buttons to increase/decrease the input value"
        step={0.1}
        value={value2}
      />
    </Flex>
  );
}

Example: ref

Set a ref on NumberField to use the Constraint Validation API or to anchor a Popover-based element.

Note that while the arrow buttons will not exceed the min/max (if set), the user is free to enter any number using the keyboard. Validation should be performed explicitly using the Constraint Validation API to ensure the value is within the specified range.

Enter a Star Wars episode number

function Example(props) {
  const [value, setValue] = React.useState('');
  const [errorMessage, setErrorMessage] = React.useState(undefined);
  const ref = React.useRef();

  React.useEffect(() => {
    if (ref.current && ref.current.checkValidity() === false) {
      setErrorMessage("That episode doesn't exist (yet)!");
    } else {
      setErrorMessage(undefined);
    }
  }, [value]);

  return (
    <NumberField
      errorMessage={errorMessage}
      id="refExampleNumberField"
      label="Enter a Star Wars episode number"
      max={9}
      min={1}
      onChange={({ value }) => {
        setValue(value);
      }}
      placeholder="Enter a number from 1–9"
      ref={ref}
      step={2}
      value={value}
    />
  );
}

function Example(props) {
  const [value, setValue] = React.useState('');
  const [errorMessage, setErrorMessage] = React.useState(undefined);
  const ref = React.useRef();
  React.useEffect(() => {
    if (ref.current && ref.current.checkValidity() === false) {
      setErrorMessage("That episode doesn't exist (yet)!");
    } else {
      setErrorMessage(undefined);
    }
  }, [value]);
  return (
    <NumberField
      errorMessage={errorMessage}
      id="refExampleNumberField"
      label="Enter a Star Wars episode number"
      max={9}
      min={1}
      onChange={({ value }) => {
        setValue(value);
      }}
      placeholder="Enter a number from 1–9"
      ref={ref}
      step={2}
      value={value}
    />
  );
}

Autofocus

NumberField intentionally lacks support for autofocus. Generally speaking,
autofocus interrupts normal page flow for screen readers making it an
anti-pattern for accessibility.

onSubmit

NumberField is commonly used as an input in forms alongside submit buttons.
In these cases, users expect that pressing Enter or Return with the input
focused will submit the form.

Out of the box, NumberField doesn't expose an onSubmit handler or
individual key event handlers due to the complexities of handling these
properly. Instead, developers are encouraged to wrap NumberField
in a <form> and attach an onSubmit handler to that <form>.

Edit page on GitHub