Skip to main content

Input

Fundamental component for inputs. Pair it with Field to connect its label, description, and errors in a form.

When to use

  • Accept one line of text from the user, such as a name, an email address, a URL, or a search term.
  • Prefer TextArea when the text spans several lines.
  • Prefer PasswordInput when the value is a password or another secret.
  • Prefer OtpInput when the value is a one-time passcode.
  • Prefer Combobox when the user picks the value from a list of suggestions.
  • Prefer Query when the field filters a list with free text and key:value qualifiers.

Validation

Set validation to show the validation status of the input. It changes the border and the outline.

Without a Field

Render the control on its own when a form field wrapper does not fit.

Examples

With TanStack Form

Use @tanstack/react-form with zod when the input needs controlled value, blur, submit, and validation state. Field.Item owns the field name and Field.Errors renders normalized validator messages.

Child elements

Compose additional visual or functional elements within the Input using children. The examples below show how to render start and end icons or buttons. The Password Input is built with this API under the hood! You must also pass the InputCapture component as children, because it renders the actual form input element! When you do not use the children API, Input renders an InputCapture for you.

When composing with interactive content (e.g. a button), consider whether that element should be tab-indexable or receive focus!

When to use InputCapture

For 90% of cases (a simple input with optional icons or validation), pass children directly to <Input> or omit children entirely. The Input renders an InputCapture for you internally, so you do not need to import or render it yourself.

InputCapture is the actual <input> element wrapper. Reach for it only when composing custom adornments: for example, a left-side prefix and a right-side suffix where the existing Input slots don't fit. When you supply your own children, you must include <InputCapture /> so the form input element is still rendered. The Password Input is built using this API under the hood.

API Reference

The Input accepts the following props in addition to the standard HTML input attributes.

PropTypeDefaultDescription
validation"error" | "success" | "warning" | false | () => "error" | "success" | "warning" | falseUse the validation prop to show if the input has a specific validation status. This will change the border and outline of the input. The false type is useful when using short-circuiting logic so that you don't need to use a ternary with undefined. Setting validation to error also sets aria-invalid.

Two standard attributes are narrowed to unions, so a typo is a type error: type accepts the native input type names, and autoComplete accepts the HTML autocomplete tokens.

InputCapture

The <input> element itself. Input renders one for you unless you pass children; then you render it yourself among your adornments. It accepts the same props as Input, minus children, and reads any prop you set on the surrounding Input through context, so id, name, type, validation, and the aria-* attributes land on the element whichever of the two you set them on.

Data AttributeValueDescription
data-slot"input"The chrome around the input.
data-slot"input-capture"The <input> element.
data-disabledpresent when disabledOn the chrome. Style with data-disabled:.
data-validation"error" | "success" | "warning"On the chrome and the <input>. Omitted when unset.