Input

Input is a component that allows users to enter text. It can be used to get user inputs in forms, search fields, and more.


Installation

npx nextui-cli@latest add input
The above command is for individual installation only. You may skip this step if @nextui-org/react is already installed globally.

Import

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.

Password Input

You can use the type property to change the input type to password.

Clear Button

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

Start & End Content

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

With Description

You can add a description to the input by passing the description 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.

Example with regex email validation:

Controlled

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

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

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 when position is outside / outside-left.
  • 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.
  • helperWrapper: Wraps the description and the errorMessage.
  • description: The description of the input.
  • errorMessage: The error message of the input.

Custom Styles

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

Custom Implementation

In case you need to customize the input even further, you can use the useInput hook to create your own implementation.

Data Attributes

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

Accessibility

  • Built with a native <input> element.
  • 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 and error message help text linked to the input via ARIA.

API

Input Props

AttributeTypeDescriptionDefault
childrenReactNodeThe content of the input.-
variantflat | bordered | faded | underlinedThe variant of the input.flat
colordefault | primary | secondary | success | warning | dangerThe color of the input.default
sizesm | md | lgThe size of the input.md
radiusnone | sm | md | lg | fullThe radius of the input.-
labelReactNodeThe content to display as the label.-
valuestringThe current value of the input (controlled).-
defaultValuestringThe default value of the input (uncontrolled).-
placeholderstringThe placeholder of the input.-
descriptionReactNodeA description for the input. Provides a hint such as specific requirements for what to choose.-
errorMessageReactNode | ((v: ValidationResult) => ReactNode)An error message for the input. It is only shown when isInvalid is set to true-
validate(value: string) => ValidationError | true | null | undefinedValidate input values when committing (e.g. on blur), returning error messages for invalid values. Validation errors are displayed upon form submission if validationBehavior is set to native. For real-time validation, use the isInvalid prop.-
validationBehaviornative | ariaWhether 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.aria
startContentReactNodeElement to be rendered in the left side of the input.-
endContentReactNodeElement to be rendered in the right side of the input.-
labelPlacementinside | outside | outside-leftThe position of the label.inside
fullWidthbooleanWhether the input should take up the width of its parent.true
isClearablebooleanWhether the input should have a clear button.false
isRequiredbooleanWhether user input is required on the input before form submission.false
isReadOnlybooleanWhether the input can be selected but not changed by the user.
isDisabledbooleanWhether the input is disabled.false
isInvalidbooleanWhether the input is invalid.false
baseRefRefObject<HTMLDivElement>The ref to the base element.-
validationStatevalid | invalidWhether the input should display its "valid" or "invalid" visual styling. (Deprecated) use isInvalid instead.-
disableAnimationbooleanWhether the input should be animated.false
classNamesRecord<"base"| "label"| "inputWrapper"| "innerWrapper"| "mainWrapper" | "input" | "clearButton" | "helperWrapper" | "description" | "errorMessage", string>Allows to set custom class names for the Input slots.-

Input Events

AttributeTypeDescription
onChangeReact.ChangeEvent<HTMLInputElement>Handler that is called when the element's value changes. You can pull out the new value by accessing event.target.value (string).
onValueChange(value: string) => voidHandler that is called when the element's value changes.
onClear() => voidHandler that is called when the clear button is clicked.