TextField

Installation

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.

Examples

Basic

With Description

With Icon

Password

Validation

TextField integrates with React Aria's validation system. Use isRequired, isInvalid, or custom validation.

Form

TextField works with the Form component for submission and validation.

API Reference

TextField

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.