Props
Usage guidelines
- Any time the user needs to enter mathematically-relevant numeric values, e.g. the quantity of a product or someone’s age.
- When accepting numerical data that is not mathematically relevant or could have semantic leading 0's, e.g. ZIP codes, phone numbers, social security numbers, etc. Use TextField instead. For telephone numbers specifically, be sure to use
type="tel"
for the best UX. Check out this blog post for tips on when a number input is a good choice. - 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.
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.
Remove the label, as this creates accessibility and usability issues.
Only place related fields on the same line.
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.
Display generic error messages, such as "There is an error".
Consider all text fields as required, unless explicitly noted as optional.
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.
import { useState } from 'react'; import { Box, Flex, NumberField } from 'gestalt'; export default function Example() { const [currentValue, setCurrentValue] = useState(); return ( <Flex alignItems="center" justifyContent="center" height="100%" width="100%" > <Box width={400}> <NumberField disabled id="variant-disabled" label="Disabled" onChange={({ value }) => { setCurrentValue(value); }} placeholder="This input is disabled" value={currentValue} /> </Box> </Flex> ); }
Helper text
Whenever you want to provide more information about a form field, you should use helperText
.
import { useState } from 'react'; import { Box, Flex, NumberField } from 'gestalt'; export default function Example() { const [currentValue, setCurrentValue] = useState(); return ( <Flex alignItems="center" justifyContent="center" height="100%" width="100%" > <Box width={400}> <NumberField id="variant-helperText" helperText="Round up to the nearest whole number" label="Average value" onChange={({ value }) => { setCurrentValue(value); }} value={currentValue} /> </Box> </Flex> ); }
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.
import { useState } from 'react'; import { Box, Flex, NumberField } from 'gestalt'; export default function Example() { const [currentValue, setCurrentValue] = useState(); return ( <Flex alignItems="center" justifyContent="center" height="100%" width="100%" > <Box width={400}> <NumberField id="variant-errorMessage" errorMessage={ currentValue === null || currentValue === undefined ? 'You must enter a number' : null } label="With an error message" onChange={({ value }) => { setCurrentValue(value); }} value={currentValue} /> </Box> </Flex> ); }
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.
import { useState } from 'react'; import { Flex, NumberField } from 'gestalt'; export default function Example() { const [value1, setValue1] = useState(); const [value2, setValue2] = useState(); return ( <Flex alignItems="center" direction="column" gap={4} justifyContent="center" height="100%" width="100%" > <Flex.Item minWidth="80%"> <NumberField helperText="Use the arrow buttons to increase/decrease the input value" id="minMaxStepExampleNumberField1" label="Stepping in intervals of 5" max={25} min={5} onChange={({ value }) => { setValue1(value); }} step={5} value={value1} /> </Flex.Item> <Flex.Item minWidth="80%"> <NumberField helperText="Use the arrow buttons to increase/decrease the input value" id="minMaxStepExampleNumberField2" label="Stepping in intervals of 0.1" max={2} min={-2} onChange={({ value }) => { setValue2(value); }} step={0.1} value={value2} /> </Flex.Item> </Flex> ); }
EnterKeyHint
The enterKeyHint
prop presents to the user a more accurate action label for the enter key on virtual keyboards. These are the values for each use case:
- "enter": inserting a new line
- "done": there is nothing more to input and the input editor will be closed
- "go": taking the user to the target of the text they typed
- "next": taking the user to the next field that will accept text
- "previous": taking the user to the previous field that will accept text
- "search": taking the user to the results of searching for the text they have typed
- "send": submitting the input, such as an email or chat
import { useState } from 'react'; import { Box, Flex, NumberField } from 'gestalt'; export default function Example() { const [currentValue, setCurrentValue] = useState(); return ( <Flex alignItems="center" justifyContent="center" height="100%" width="100%" > <Box width={300}> <NumberField enterKeyHint="next" id="enterKeyHint" label="Age" onChange={({ value }) => { setCurrentValue(value); }} value={currentValue} /> </Box> </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.
import { useEffect, useRef, useState } from 'react'; import { Box, Flex, NumberField } from 'gestalt'; export default function Example() { const [currentValue, setCurrentValue] = useState(); const [errorMessage, setErrorMessage] = useState(undefined); const ref = useRef(); useEffect(() => { if (ref.current && ref.current.checkValidity() === false) { setErrorMessage("That episode doesn't exist (yet)!"); } else { setErrorMessage(undefined); } }, [currentValue]); return ( <Flex alignItems="center" justifyContent="center" height="100%" width="100%" > <Box width={400}> <NumberField errorMessage={errorMessage} id="refExampleNumberField" label="Enter a Star Wars episode number" max={9} min={1} onChange={({ value }) => { setCurrentValue(value); }} placeholder="Enter a number from 1–9" ref={ref} step={2} value={currentValue} /> </Box> </Flex> ); }
Component quality checklist
Quality item | Status | Status description |
---|---|---|
Figma Library | Ready | Component is available in Figma across all platforms. |
Responsive Web | Ready | Component is available in code for web and mobile web. |
iOS | Component is not currently available in code for iOS. | |
Android | Component is not currently available in code for Android. |
Related
TextField
When accepting numerical data that is not mathematically relevant or could have semantic leading 0's, e.g. ZIP codes, phone numbers, social security numbers, etc. Use TextField instead. For telephone numbers specifically, be sure to use type="tel"
for the best UX. Check out this blog post for tips on when a number input is a good choice.