Docs
Components
TextField

TextField

A text field allows a user to enter a plain text value with a keyboard.

TextField is a client-only adapter around React Aria Components. It exists to: - Explicitly define a client boundary ("use client") - Isolate React Aria as an implementation detail - Provide a stable public API and consistent developer experience TextField is not meant to be used directly. It should be composed into Field for proper layout and structure. See the Forms architecture overview to understand how TextField, Field, and Form work together.

Installation

CLI

Manual

npx shadcn@latest add @kanpeki/text-field

Overview

TextField is a behavior and accessibility layer built on React Aria. It is not a visual component—it provides:

Automatic ID wiring between label, input, description, and error
Validation state management
Keyboard and focus handling
ARIA attributes for screen readers

TextField is designed to be composed into the Field component, which handles layout and visual structure.

Before you start

TextField is not responsible for:

Layout or visual structure
Rendering labels, descriptions, or error messages
Styling or positioning

For complete form fields, use Field as your composition root. TextField handles behavior; Field handles presentation.

Recommended reading:

Field documentation – Learn about the composition root
Forms architecture overview – Understand how all pieces fit together

Anatomy

TextField wraps your input and connects it to Field's label, description, and error elements.

import { Field } from "~/components/ui/field";
import { Input } from "~/components/ui/input";
import { TextField } from "~/components/ui/text-field";

<Field.Root render={<TextField type="email" />}>
  <Field.Label>Email</Field.Label>
  <Input placeholder="john@example.com" />
  <Field.Description>We'll never share your email.</Field.Description>
  <Field.Error />
</Field.Root>;

The render prop on Field.Root accepts the TextField component. This pattern allows Field to provide layout while TextField provides behavior.

Code

Form

TextField works with the Form component for submission and validation.

Preview

Code

Props

TextField accepts all props from React Aria's TextField.

Prop	Type	Default	Description
`type`	`string`	`"text"`	Input type (email, password, etc.)
`isRequired`	`boolean`	`false`	Whether the field is required
`isInvalid`	`boolean`	`false`	Whether the field is in error state
`isDisabled`	`boolean`	`false`	Whether the field is disabled
`isReadOnly`	`boolean`	`false`	Whether the field is read-only
`value`	`string`		Controlled value
`defaultValue`	`string`		Default value (uncontrolled)
`onChange`	`(value: string) => void`		Called when value changes
`name`	`string`		Form field name
`autoComplete`	`string`		Autocomplete hint
`maxLength`	`number`		Maximum character length
`minLength`	`number`		Minimum character length
`pattern`	`string`		Validation pattern

Accessibility

When TextField is composed with Field:

Field.Label is automatically associated via aria-labelledby
Field.Description is associated via aria-describedby
Field.Error is associated via aria-describedby when invalid
Focus management and keyboard navigation are handled automatically

Without TextField

If you use Field.Root with Input directly (without TextField), you must manually wire IDs:

<Field.Root>
  <Field.Label htmlFor="email">Email</Field.Label>
  <Input id="email" aria-describedby="email-desc" />
  <Field.Description id="email-desc">Helper text</Field.Description>
</Field.Root>

This approach loses React Aria's automatic association and is not recommended for production forms.

Textarea Toast

On This Page

Installation
Overview
Before you start
Anatomy
Examples
Basic
With Description
With Icon
Password
Validation
Form
Props
Accessibility
Without TextField

Contribute