Number Input

The numeric input component is designed for users to enter a number, and increase or decrease the value using stepper buttons

Installation

The above command is for individual installation only. You may skip this step if @heroui/react is already installed globally.

Usage

Disabled

Read Only

Required

If you pass the isRequired property to the input, it will have a danger asterisk at the end of the label and the input will be required.

Sizes

Colors

Variants

Radius

Label Placements

You can change the position of the label by setting the labelPlacement property to inside, outside or outside-left.

Note: If the label is not passed, the labelPlacement property will be outside by default.

Clear Button

If you pass the isClearable property to the input, it will have a clear button at the end of input, it will be visible when input has a value.

Hide Stepper

You can hide the stepper buttons by passing the hideStepper property.

Start & End Content

You can use the startContent and endContent properties to add content to the start and end of NumberInput.

With Label

You can add a label to the input by passing the label property.

With Description

You can add a description to the input by passing the description property.

With Min Value

You can set the minimum value of the input by passing the minValue property.

With Max Value

You can set the maximum value of the input by passing the maxValue property.

With Wheel Disabled

By default, you can increase or decrease the value with scroll wheel. You can disable changing the vaule with scroll in NumberInput by passing the isWheelDisabled property.

With Format Options

You can format the value of the input by passing the formatOptions property.

With Error Message

You can combine the isInvalid and errorMessage properties to show an invalid input. errorMessage is only shown when isInvalid is set to true.

Controlled

You can use the value and onValueChange properties to control the input value.

Note: HeroUI NumberInput also supports native events like onChange, useful for form libraries such as Formik and React Hook Form.

With Form

NumberInput can be used with a Form component to leverage form state management. For more on form and validation behaviors, see the Forms guide.

Custom Validation

In addition to built-in constraints, you can provide a function to the validate property for custom validation.

Realtime Validation

If you want to display validation errors while the user is typing, you can control the field value and use the isInvalid prop along with the errorMessage prop.

Server Validation

Client-side validation provides immediate feedback, but you should also validate data on the server to ensure accuracy and security. HeroUI allows you to display server-side validation errors by using the validationErrors prop in the Form component. This prop should be an object where each key is the field name and the value is the error message.

Slots

• base: Input wrapper, it handles alignment, placement, and general appearance.
• label: Label of the input, it is the one that is displayed above, inside or left of the input.
• mainWrapper: Wraps the inputWrapper
• inputWrapper: Wraps the label (when it is inside) and the innerWrapper.
• innerWrapper: Wraps the input, the startContent and the endContent.
• input: The input element.
• clearButton: The clear button, it is at the end of the input.
• stepperButton: The stepper button to increase or decrease the value.
• stepperWrapper: The wrapper for the stepper.
• description: The description of NumberInput.
• errorMessage: The error message of NumberInput.

Custom Styles

You can customize the NumberInput component by passing custom Tailwind CSS classes to the component slots.

Data Attributes

NumberInput has the following attributes on the base element:

• data-invalid: When the input is invalid. Based on isInvalid prop.
• data-required: When the input is required. Based on isRequired prop.
• data-readonly: When the input is readonly. Based on isReadOnly prop.
• data-hover: When the input is being hovered. Based on useHover
• data-focus: When the input is being focused. Based on useFocusRing.
• data-focus-within: When the input is being focused or any of its children. Based on useFocusWithin.
• data-focus-visible: When the input is being focused with the keyboard. Based on useFocusRing.
• data-disabled: When the input is disabled. Based on isDisabled prop.
• data-filled: When the input has content, placeholder, start content or the placeholder is shown.
• data-has-elements: When the input has any element (label, helper text, description, error message).
• data-has-helper: When the input has helper text.
• data-has-description: When the input has a description.
• data-has-label: When the input has a label.
• data-has-value: When the input has a value (placeholder is not shown).

Accessibility

• Built with a native <input> element with type="number".
• Visual and ARIA labeling support.
• Change, clipboard, composition, selection, and input event support.
• Required and invalid states exposed to assistive technology via ARIA.
• Support for description, helper text, and error message linked to the input via ARIA.

API

NumberInput Props

NumberInput Events