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.
`ref`	`React.Element<"input">`	-
	Ref that is forwarded to the underlying input element.
`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

When accepting telephone numbers, or numerical data that could contain leading 0's (e.g. ZIP codes). Use TextField with type="tel" instead.
Situations where text needs to be entered. Use TextField or TextArea instead.

Best practices

Use helper text for important information. Helper text helps users understand how to complete the number field or to indicate any needed input.

Don't

Put essential information in the placeholder text, since it disappears when the user types. The placeholder text is not a replacement for the label.

Always ensure the number field has a visible label. The label provides context and supports users when filling in information.

Don't

Remove the label, as this creates accessibility and usability issues.

Only place related fields on the same line.

Don't

Place unrelated number fields on the same line, as this can create comprehension issues.

Provide clear and useful error messages that help the user fix the issue. Error messages should be displayed in a timely manner — typically once the field loses focus or when the form is submitted.

Don't

Display generic error messages, such as "There is an error".

Consider all text fields as required, unless explicitly noted as optional.

Don't

Mark fields as required.

Accessibility

Comprehension

Be sure to provide instructions to help users understand how to complete the form and use individual form controls.

Labels

Ensure the labels are precise and concise. Labels should only describe the number field they are associated with, and they must be visible.

Validation

When providing a validation message, make sure the instructions are clear and help users complete the field. For example, "Value must be greater than 20". In addition, use the helper text to provide instructions to help users understand how to complete the number field or to indicate any needed input, allowed formats, timing limitations, or other pertinent information.
These practices give screen readers and users of assistive technologies more information about the form, helping them to fill it out.

NumberField has conventional keyboard support.

Users relying on the keyboard expect to move focus to each NumberField by using the tab key or shift+tab when moving backwards
Users can press the up and down arrow keys to adjust the field value
Setting disabled will prevent NumberField from receiving keyboard focus or input

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>.

Localization

Be sure to localize errorMessage, helperText, label, and placeholder.

Variants

Disabled

Disabled NumberFields cannot be interacted with using the mouse or keyboard.

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

  return (
    <NumberField
      disabled
      id="variant-disabled"
      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="variant-disabled"
      label="Disabled"
      onChange={({ value }) => {
        setValue(value);
      }}
      placeholder="This input is disabled"
      value={value}
    />
  );
}

Helper text

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

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

  return (
    <Box padding={2} color="white">
      <NumberField
        id="variant-helperText"
        helperText="Round up to the nearest whole number"
        label="Average value"
        onChange={({ value }) => {
          setValue(value);
        }}
        value={value}
      />
    </Box>
  );
}

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

  return (
    <Box padding={2} color="white">
      <NumberField
        id="variant-helperText"
        helperText="Round up to the nearest whole number"
        label="Average value"
        onChange={({ value }) => {
          setValue(value);
        }}
        value={value}
      />
    </Box>
  );
}

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.

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

  return (
    <NumberField
      id="variant-errorMessage"
      errorMessage={value === null || value === undefined ? "You must enter a number" : null}
      onChange={({ value }) => {
        setValue(value);
      }}
      label="With an error message"
      value={value}
    />
  );
}

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

  return (
    <NumberField
      id="variant-errorMessage"
      errorMessage={value === null || value === undefined ? "You must enter a number" : null}
      onChange={({ value }) => {
        setValue(value);
      }}
      label="With an error message"
      value={value}
    />
  );
}

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.

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>
  );
}

Refs

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.

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}
    />
  );
}

TextField
For text input, telephone numbers, or numerical input with possible leading 0's (e.g. ZIP codes), use TextField. (For telephone numbers, use <TextField type="tel" />.)

Edit page on GitHub

NumberField

Props

Usage guidelines

Best practices

Accessibility

Comprehension

Labels

Validation

Keyboard navigation

Autofocus

onSubmit

Localization

Variants

Disabled

Helper text

Error message

Min/max/step

Refs

Related