1. Components
  2. Forms and inputs
  3. NumberField

NumberField

NumberField allows a user to enter a number, and increment or decrement the value using stepper buttons.

Aria docsAria API ReferenceReport an issueEdit this page
<NumberField label="Width" defaultValue={1024} />

Installation

npx dotui-cli@latest add number-field

Usage

Use a NumberField to allow a user to enter a number.

Options

Number formatting

The NumberField value can be formatted by using the formatOptions prop. formatOptions is compatible with the option parameter of Intl.NumberFormat and is applied based on the current locale.

<NumberField
  label="Decimal"
  defaultValue={0}
  formatOptions={{
    signDisplay: "exceptZero",
    minimumFractionDigits: 1,
    maximumFractionDigits: 2,
  }}
/>
<NumberField
  label="Percentage"
  defaultValue={0.05}
  formatOptions={{
    style: "percent",
  }}
/>
<NumberField
  label="Currency"
  defaultValue={45}
  formatOptions={{
    style: "currency",
    currency: "EUR",
    currencyDisplay: "code",
    currencySign: "accounting",
  }}
/>
<NumberField
  label="Unit"
  defaultValue={4}
  formatOptions={{
    style: "unit",
    unit: "inch",
    unitDisplay: "long",
  }}
/>

Size

Use the size prop to control the size of the NumberField. The default size is "md".

<NumberField size="sm" />
<NumberField size="md" />
<NumberField size="lg" />

Label

A visual label can be provided for the NumberField using the label prop or a hidden label using aria-label prop.

<NumberField label="Width" />
<NumberField aria-label="Width" />

Description

A description can be supplied to a NumberField via the description prop. The description is always visible unless the isInvalid prop is set to true and an error message is provided.

Enter the desired width.
<NumberField label="Width" description="Enter the desired width." />

Error message

An errorMessage can be supplied to a NumberField, which will be displayed when the isInvalid prop is set to true.

Please fill out this field.
<NumberField
  label="Width"
  isInvalid
  errorMessage="Please fill out this field."
/>

Disabled

Use the isDisabled prop to disable the NumberField.

<NumberField isDisabled />

ReadOnly

The isReadOnly boolean prop makes the NumberField's text content immutable. Unlike isDisabled, the NumberField remains focusable and the contents can still be copied.

<NumberField isReadOnly />

Required

Use the isRequired prop to mark the NumberField as required. Use the necessityIndicator prop to control the visual style of the required state.

<NumberField label="Width" isRequired />
<NumberField label="Width" isRequired necessityIndicator="icon" />
<NumberField label="Width" isRequired necessityIndicator="label" />
<NumberField label="Width" necessityIndicator="label" />

Uncontrolled

Use the defaultValue prop to set the default input value.

<NumberField defaultValue={80} />

Controlled

Use the value and onChange props to control the value of the input.

mirrored number: 69

const [value, setValue] = React.useState(69);
return <NumberField value={value} onChange={setValue} />;

Composition

If you need to customize things further, you can drop down to the composition level.

Enter the disired quantity.
<NumberFieldRoot>
  <Label>Quantity</Label>
  <Group className="flex items-center gap-2">
    <Button slot="decrement">
      <MinusIcon />
    </Button>
    <InputRoot>
      <Input />
    </InputRoot>
    <Button slot="increment">
      <PlusIcon />
    </Button>
  </Group>
  <Description>Enter the disired quantity.</Description>
</NumberFieldRoot>

API Reference

PropTypeDefaultDescription
size"sm" | "md" | "lg""md"The size of the input.
labelReactNodeThe content to display as the label.
descriptionReactNodeA description for the field. Provides a hint such as specific requirements for what to choose.
errorMessageReactNode | (v: ValidationResult) => ReactNodeAn error message for the field.
decrementAriaLabelstring-A custom aria-label for the decrement button. If not provided, the localized string "Decrement" is used.
incrementAriaLabelstring-A custom aria-label for the increment button. If not provided, the localized string "Increment" is used.
isWheelDisabledboolean-Enables or disables changing the value with scroll.
formatOptionsIntl.NumberFormatOptions-Formatting options for the value displayed in the number field. This also affects what characters are allowed to be typed by the user.
isDisabledboolean-Whether the input is disabled.
isReadOnlyboolean-Whether the input can be selected but not changed by the user.
isRequiredboolean-Whether user input is required on the input before form submission.
isInvalidboolean-Whether the value is invalid.
validate(value: string) => ValidationError | true | null | undefined-A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if validationBehavior="native". For realtime validation, use the isInvalid prop instead.
autoFocusboolean-Whether the element should receive focus on render.
valuenumber-The current value (controlled).
defaultValuenumber-The default value (uncontrolled).
minValuenumber-The smallest value allowed for the input.
maxValuenumber-The largest value allowed for the input.
stepnumber-The amount that the input value changes with each increment or decrement "tick".
validationBehavior'native' | 'aria''native'Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.
namestring-The name of the input element, used when submitting an HTML form.
childrenReactNode | (values: NumberFieldRenderProps & {defaultChildren: ReactNode | undefined}) => ReactNode-The children of the component. A function may be provided to alter the children based on component state.
classNamestring-The CSS className for the element.
styleCSSProperties | (values: NumberFieldRenderProps & {defaultStyle: CSSProperties}) => CSSProperties-The inline style for the element. A function may be provided to compute the style based on component state.
EventTypeDescription
onFocus(e: FocusEvent<Target>) => voidHandler that is called when the element receives focus.
onBlur(e: FocusEvent<Target>) => voidHandler that is called when the element loses focus.
onFocusChange(isFocused: boolean) => voidHandler that is called when the element's focus status changes.
onKeyDown(e: KeyboardEvent) => voidHandler that is called when a key is pressed.
onKeyUp(e: KeyboardEvent) => voidHandler that is called when a key is released.
onChange(value: T) => voidHandler that is called when the value changes.
onCopyClipboardEventHandler<HTMLInputElement>Handler that is called when the user copies text.
onCutClipboardEventHandler<HTMLInputElement>Handler that is called when the user cuts text.
onPasteClipboardEventHandler<HTMLInputElement>Handler that is called when the user pastes text.
onCompositionStartCompositionEventHandler<HTMLInputElement>Handler that is called when a text composition system starts a new text composition session.
onCompositionEndCompositionEventHandler<HTMLInputElement>Handler that is called when a text composition system completes or cancels the current text composition session.
onCompositionUpdateCompositionEventHandler<HTMLInputElement>Handler that is called when a new character is received in the current text composition session.
onSelectReactEventHandler<HTMLInputElement>Handler that is called when text in the input is selected.
onBeforeInputFormEventHandler<HTMLInputElement>Handler that is called when the input value is about to be modified.
onInputFormEventHandler<HTMLInputElement>Handler that is called when the input value is modified.
Data attributeDescription
[data-disabled]Whether the text field is disabled.
[data-invalid]Whether the text field is invalid.
SearchFieldCheckbox
dotUI

Bringing singularity to the web.

Community

Built by mehdibha. The source code is available on GitHub.