# Text Field · HeroUI

> Composition-friendly text fields with labels, descriptions, and inline validation

- Page: https://jiguang132.com/systems/heroui/docs/components/textfield
- Based on: HeroUI documentation (Apache-2.0) @ 60edd8ed751b1d2a270623fbb182bbcfa8baa9af

## Import

```tsx
import { TextField } from '@heroui/react';
```

### Usage


> Example `textfield-basic`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/textfield


### Anatomy

```tsx
import {TextField, Label, Input, Description, FieldError} from '@heroui/react';

export default () => (
  <TextField>
    <Label />
    <Input />
    <Description />
    <FieldError />
  </TextField>
)
```

>  **TextField** combines label, input, description, and error into a single accessible component.
For standalone inputs, use **[Input](/systems/heroui/docs/components/input)** or **[TextArea](/systems/heroui/docs/components/textarea)**.

### With Description


> Example `textfield-with-description`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/textfield


### Required Field


> Example `textfield-required`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/textfield


### Validation

Use `isInvalid` together with `FieldError` to surface validation messages.


> Example `textfield-validation`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/textfield


### Controlled

Control the value to synchronize counters, previews, or formatting.


> Example `textfield-controlled`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/textfield


### Error Message


> Example `textfield-with-error`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/textfield


### Disabled State


> Example `textfield-disabled`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/textfield


### TextArea

Use [TextArea](/systems/heroui/docs/components/textarea) instead of [Input](/systems/heroui/docs/components/input) for multiline content.


> Example `textfield-textarea`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/textfield


### Input Types


> Example `textfield-input-types`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/textfield


### Full Width


> Example `textfield-full-width`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/textfield


### In Surface

When used inside a [Surface](/systems/heroui/docs/components/surface) component, use `variant="secondary"` on Input or TextArea components to apply the lower emphasis variant suitable for surface backgrounds.


> Example `textfield-on-surface`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/textfield


### Custom Render Function


> Example `textfield-custom-render-function`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/textfield


## Styling

### Passing Tailwind CSS classes

```tsx
import {TextField, Label, Input, Description} from '@heroui/react';

function CustomTextField() {
  return (
    <TextField className="gap-2 rounded-xl border border-border/60 bgsurface p-4 shadow-sm">
      <Label className="text-sm font-semibold text-default-700">
        Project name
      </Label>
      <Input className="rounded-lg border border-border/60 bgsurface px-3 py-2" />
      <Description className="text-xs text-default-500">
        Keep it short and memorable.
      </Description>
    </TextField>
  );
}
```

### Customizing the component classes

TextField has minimal default styling. Override the `.textfield` class to customize the container styling.

```css
@layer components {
  .textfield {
    @apply flex flex-col gap-1;
  }

  /* When invalid, the description is hidden automatically */
  .textfield[data-invalid="true"] [data-slot="description"],
  .textfield[aria-invalid="true"] [data-slot="description"] {
    @apply hidden;
  }

  /* Description has default padding */
  .textfield [data-slot="description"] {
    @apply px-1;
  }
}
```

### CSS Classes

- `.textfield` – Root container with minimal styling (`flex flex-col gap-1`)

> **Note:** Child components ([Label](/systems/heroui/docs/components/label), [Input](/systems/heroui/docs/components/input), [TextArea](/systems/heroui/docs/components/textarea), [Description](/systems/heroui/docs/components/description), [FieldError](/systems/heroui/docs/components/field-error)) have their own CSS classes and styling. See their respective documentation for customization options.

### Interactive States

TextField automatically manages these data attributes based on its state:

- **Invalid**: `[data-invalid="true"]` or `[aria-invalid="true"]` - Automatically hides the description slot when invalid
- **Disabled**: `[data-disabled="true"]` - Applied when `isDisabled` is true
- **Focus Within**: `[data-focus-within="true"]` - Applied when any child input is focused
- **Focus Visible**: `[data-focus-visible="true"]` - Applied when focus is visible (keyboard navigation)

Additional attributes are available through render props (see TextFieldRenderProps below).

## API Reference

### TextField Props

TextField inherits all props from React Aria's [TextField](https://react-spectrum.adobe.com/react-aria/TextField.html) component.

#### Base Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `React.ReactNode \| (values: TextFieldRenderProps) => React.ReactNode` | - | Child components (Label, Input, etc.) or render function. |
| `className` | `string \| (values: TextFieldRenderProps) => string` | - | CSS classes for styling, supports render props. |
| `style` | `React.CSSProperties \| (values: TextFieldRenderProps) => React.CSSProperties` | - | Inline styles, supports render props. |
| `fullWidth` | `boolean` | `false` | Whether the text field should take full width of its container |
| `id` | `string` | - | The element's unique identifier. |
| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TextFieldRenderProps>` | - | Overrides the default DOM element with a custom render function.|

#### Validation Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `isRequired` | `boolean` | `false` | Whether user input is required before form submission. |
| `isInvalid` | `boolean` | - | Whether the value is invalid. |
| `validate` | `(value: string) => ValidationError \| true \| null \| undefined` | - | Custom validation function. |
| `validationBehavior` | `'native' \| 'aria'` | `'native'` | Whether to use native HTML form validation or ARIA attributes. |
| `validationErrors` | `string[]` | - | Server-side validation errors. |

#### Value Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string` | - | Current value (controlled). |
| `defaultValue` | `string` | - | Default value (uncontrolled). |
| `onChange` | `(value: string) => void` | - | Handler called when the value changes. |

#### State Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `isDisabled` | `boolean` | - | Whether the input is disabled. |
| `isReadOnly` | `boolean` | - | Whether the input can be selected but not changed. |

#### Form Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `name` | `string` | - | Name of the input element, for HTML form submission. |
| `autoFocus` | `boolean` | - | Whether the element should receive focus on render. |

#### Accessibility Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `aria-label` | `string` | - | Accessibility label when no visible label is present. |
| `aria-labelledby` | `string` | - | ID of elements that label this field. |
| `aria-describedby` | `string` | - | ID of elements that describe this field. |
| `aria-details` | `string` | - | ID of elements with additional details. |

### Composition Components

TextField works with these separate components that should be imported and used directly:

- **Label** - Field label component from `@heroui/react`
- **Input** - Single-line text input from `@heroui/react`
- **TextArea** - Multi-line text input from `@heroui/react`
- **Description** - Helper text component from `@heroui/react`
- **FieldError** - Validation error message from `@heroui/react`

Each of these components has its own props API. Use them directly within TextField for composition:

```tsx
<TextField isRequired isInvalid={hasError}>
  <Label>Email Address</Label>
  <Input type="email" value={email} onChange={(e) => setEmail(e.target.value)} />
  <Description>We'll never share your email.</Description>
  <FieldError>Please enter a valid email address.</FieldError>
</TextField>
```

### TextFieldRenderProps

When using render props with `className`, `style`, or `children`, these values are available:

| Prop | Type | Description |
|------|------|-------------|
| `isDisabled` | `boolean` | Whether the field is disabled. |
| `isInvalid` | `boolean` | Whether the field is currently invalid. |
| `isReadOnly` | `boolean` | Whether the field is read-only. |
| `isRequired` | `boolean` | Whether the field is required. |
| `isFocused` | `boolean` | Whether the field is currently focused (DEPRECATED - use `isFocusWithin`). |
| `isFocusWithin` | `boolean` | Whether any child element is focused. |
| `isFocusVisible` | `boolean` | Whether focus is visible (keyboard navigation). |

---

Index of all JGuang resources: https://jiguang132.com/llms.txt