# Field

URL: https://ark-ui.com/docs/react/components/field
Markdown: https://ark-ui.com/docs/react/components/field.md

Provides a flexible container for form inputs, labels, and helper text.

---

---
id: field
title: Field
description: Provides a flexible container for form inputs, labels, and helper text.
---



## Anatomy



```tsx
<Field.Root>
  <Field.Label>
    <Field.Indicator />
  </Field.Label>
  <Field.Input />
  <Field.Textarea />
  <Field.Select />
  <Field.HelperText />
  <Field.ErrorText />
</Field.Root>
```

## Examples

The `Field` component provides contexts such as `invalid`, `disabled`, `required`, and `readOnly` for form elements.
While most Ark UI components natively support these contexts, you can also use the `Field` component with standard HTML
form elements.

### Input

This example shows how to use the `Field` component with a standard input field.

```tsx
import { Field } from '@ark-ui/react/field'
import styles from 'styles/field.module.css'

export const Input = () => (
  <Field.Root className={styles.Root}>
    <Field.Label className={styles.Label}>Label</Field.Label>
    <Field.Input className={styles.Input} />
    <Field.HelperText className={styles.HelperText}>Some additional Info</Field.HelperText>
    <Field.ErrorText className={styles.ErrorText}>Error Info</Field.ErrorText>
  </Field.Root>
)
```

### Disabled

Set `disabled` on the root to disable the control and mark every part with `data-disabled`.

```tsx
import { Field } from '@ark-ui/react/field'
import styles from 'styles/field.module.css'

export const Disabled = () => (
  <Field.Root className={styles.Root} disabled>
    <Field.Label className={styles.Label}>Label</Field.Label>
    <Field.Input className={styles.Input} />
    <Field.HelperText className={styles.HelperText}>Some additional Info</Field.HelperText>
    <Field.ErrorText className={styles.ErrorText}>Error Info</Field.ErrorText>
  </Field.Root>
)
```

### Invalid

Set `invalid` to show the error text and mark the control with `aria-invalid`. The error text stays mounted and hidden
while the field is valid.

```tsx
import { Field } from '@ark-ui/react/field'
import styles from 'styles/field.module.css'

export const Invalid = () => (
  <Field.Root className={styles.Root} invalid>
    <Field.Label className={styles.Label}>Email</Field.Label>
    <Field.Input className={styles.Input} placeholder="me@example.com" />
    <Field.ErrorText className={styles.ErrorText}>This is an error text</Field.ErrorText>
  </Field.Root>
)
```

### Indicator

`Field.Indicator` is shown only when its `type` matches the field state: `required`, `invalid`, `valid` or `validating`.
Use it inside the label to show a required marker.

```tsx
import { Field } from '@ark-ui/react/field'
import styles from 'styles/field.module.css'

export const Indicator = () => (
  <Field.Root className={styles.Root} required>
    <Field.Label className={styles.Label}>
      Username
      <Field.Indicator type="required">*</Field.Indicator>
    </Field.Label>
    <Field.Input className={styles.Input} />
  </Field.Root>
)
```

### Validation

The field validates the control natively, using attributes like `required` and `type="email"`. Set `validationMode` to
choose when results show (`onSubmit`, `onBlur` or `onChange`), and pass `match` to `Field.ErrorText` to show it only for
one native failure such as `valueMissing` or `typeMismatch`.

```tsx
import { Field } from '@ark-ui/react/field'
import button from 'styles/button.module.css'
import styles from 'styles/field.module.css'

export const Validation = () => (
  <form className="stack" noValidate onSubmit={(event) => event.preventDefault()}>
    <Field.Root className={styles.Root} required validationMode="onBlur">
      <Field.Label className={styles.Label}>
        Email
        <Field.Indicator type="required">*</Field.Indicator>
      </Field.Label>
      <Field.Input className={styles.Input} type="email" placeholder="me@example.com" />
      <Field.HelperText className={styles.HelperText}>We'll never share your email.</Field.HelperText>
      <Field.ErrorText className={styles.ErrorText} match="valueMissing">
        Email is required
      </Field.ErrorText>
      <Field.ErrorText className={styles.ErrorText} match="typeMismatch">
        Enter a valid email address
      </Field.ErrorText>
    </Field.Root>
    <button className={button.Root} type="submit">
      Submit
    </button>
  </form>
)
```

### Custom Validation

Pass `validate` to run your own rules. Return an error message, a list of messages, or nothing when the value is valid.
It can also return a promise. The messages are available as `errors` on the field context.

```tsx
import { Field } from '@ark-ui/react/field'
import button from 'styles/button.module.css'
import styles from 'styles/field.module.css'

const reserved = ['admin', 'root', 'support']

export const CustomValidation = () => (
  <form className="stack" noValidate onSubmit={(event) => event.preventDefault()}>
    <Field.Root
      className={styles.Root}
      required
      validationMode="onChange"
      validate={({ value }) => {
        if (value.length > 0 && value.length < 3) return 'Use at least 3 characters'
        if (reserved.includes(value.toLowerCase())) return 'This username is reserved'
      }}
    >
      <Field.Label className={styles.Label}>Username</Field.Label>
      <Field.Input className={styles.Input} />
      <Field.Context>
        {(field) => <Field.ErrorText className={styles.ErrorText}>{field.errors[0]}</Field.ErrorText>}
      </Field.Context>
    </Field.Root>
    <button className={button.Root} type="submit">
      Submit
    </button>
  </form>
)
```

### Server Errors

Pass `errors` to show errors that come from outside the field, such as a server response. The field is invalid while
`errors` is not empty.

```tsx
import { Field } from '@ark-ui/react/field'
import { useState } from 'react'
import button from 'styles/button.module.css'
import styles from 'styles/field.module.css'

export const ServerErrors = () => {
  const [errors, setErrors] = useState<string[]>([])

  return (
    <form
      className="stack"
      onSubmit={(event) => {
        event.preventDefault()
        setErrors(['This email is already registered'])
      }}
    >
      <Field.Root className={styles.Root} errors={errors}>
        <Field.Label className={styles.Label}>Email</Field.Label>
        <Field.Input className={styles.Input} type="email" name="email" defaultValue="taken@example.com" />
        <Field.HelperText className={styles.HelperText}>Submit to check the email with the server.</Field.HelperText>
        <Field.Context>
          {(field) => <Field.ErrorText className={styles.ErrorText}>{field.errors[0]}</Field.ErrorText>}
        </Field.Context>
      </Field.Root>
      <button className={button.Root} type="submit">
        Submit
      </button>
    </form>
  )
}
```

### Textarea

This example illustrates how to use the `Field` component with a textarea element.

```tsx
import { Field } from '@ark-ui/react/field'
import styles from 'styles/field.module.css'

export const Textarea = () => (
  <Field.Root className={styles.Root}>
    <Field.Label className={styles.Label}>Label</Field.Label>
    <Field.Textarea className={styles.Textarea} />
    <Field.HelperText className={styles.HelperText}>Some additional Info</Field.HelperText>
    <Field.ErrorText className={styles.ErrorText}>Error Info</Field.ErrorText>
  </Field.Root>
)
```

### Textarea Autoresize

Pass the `autoresize` prop to the `Textarea` component to enable automatic resizing as the user types.

```tsx
import { Field } from '@ark-ui/react/field'
import styles from 'styles/field.module.css'

export const TextareaAutoresize = () => (
  <Field.Root className={styles.Root}>
    <Field.Label className={styles.Label}>Label</Field.Label>
    <Field.Textarea className={styles.Textarea} autoresize />
    <Field.HelperText className={styles.HelperText}>Some additional Info</Field.HelperText>
    <Field.ErrorText className={styles.ErrorText}>Error Info</Field.ErrorText>
  </Field.Root>
)
```

### Select

This example demonstrates how to integrate the `Field` component with a select dropdown.

```tsx
import { Field } from '@ark-ui/react/field'
import styles from 'styles/field.module.css'

export const Select = () => (
  <Field.Root className={styles.Root}>
    <Field.Label className={styles.Label}>Label</Field.Label>
    <Field.Select className={styles.Select}>
      <option value="1">Option 1</option>
      <option value="2">Option 2</option>
      <option value="3">Option 3</option>
    </Field.Select>
    <Field.HelperText className={styles.HelperText}>Some additional Info</Field.HelperText>
    <Field.ErrorText className={styles.ErrorText}>Error Info</Field.ErrorText>
  </Field.Root>
)
```

### Checkbox

This example demonstrates how to integrate the `Field` and `Checkbox` components.

```tsx
import { Checkbox } from '@ark-ui/react/checkbox'
import { Field } from '@ark-ui/react/field'
import { CheckIcon, MinusIcon } from 'lucide-react'
import styles from 'styles/checkbox.module.css'
import field from 'styles/field.module.css'

export const WithField = () => (
  <Field.Root className={field.Root} data-inline>
    <Checkbox.Root className={styles.Root}>
      <Checkbox.Control className={styles.Control}>
        <Checkbox.Indicator className={styles.Indicator}>
          <CheckIcon />
        </Checkbox.Indicator>
        <Checkbox.Indicator className={styles.Indicator} indeterminate>
          <MinusIcon />
        </Checkbox.Indicator>
      </Checkbox.Control>
      <Checkbox.Label className={styles.Label}>Label</Checkbox.Label>
      <Checkbox.HiddenInput />
    </Checkbox.Root>
    <Field.HelperText className={field.HelperText}>Additional Info</Field.HelperText>
    <Field.ErrorText className={field.ErrorText}>Error Info</Field.ErrorText>
  </Field.Root>
)
```

### Root Provider

An alternative way to control the field is to use the `RootProvider` component and the `useField` hook. This way you can
access the state and methods from outside the component.

```tsx
import { Field, useField } from '@ark-ui/react/field'
import { useState } from 'react'
import styles from 'styles/field.module.css'
import button from 'styles/button.module.css'

export const RootProvider = () => {
  const [invalid, setInvalid] = useState(false)
  const field = useField({ invalid })

  return (
    <>
      <button className={button.Root} style={{ marginBottom: '1rem' }} onClick={() => setInvalid((prev) => !prev)}>
        Toggle Invalid
      </button>
      <Field.RootProvider className={styles.Root} value={field}>
        <Field.Label className={styles.Label}>Label</Field.Label>
        <Field.Input className={styles.Input} />
        <Field.HelperText className={styles.HelperText}>Some additional Info</Field.HelperText>
        <Field.ErrorText className={styles.ErrorText}>Error Info</Field.ErrorText>
      </Field.RootProvider>
    </>
  )
}
```

### Custom Control

Use the `Field.Context` or `useFieldContext` hook to access the internal state of the field.This can help you wire up
custom controls with the `Field` component.

```tsx
import { Field } from '@ark-ui/react/field'
import styles from 'styles/field.module.css'

export const CustomControl = () => (
  <Field.Root className={styles.Root} invalid>
    <Field.Label className={styles.Label}>Any Control</Field.Label>
    <Field.Context>{(context) => <input {...context.getInputProps()} />}</Field.Context>
    <Field.HelperText className={styles.HelperText}>Uses getInputProps() for maximum flexibility</Field.HelperText>
    <Field.ErrorText className={styles.ErrorText}>This field has an error</Field.ErrorText>
  </Field.Root>
)
```

## API Reference

### Root

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

**`disabled`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Indicates whether the field is disabled.

**`ids`**
Type: `ElementIds`
Required: false
Default Value: `undefined`
Description: The ids of the field parts.

**`invalid`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Indicates whether the field is invalid.

**`readOnly`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Indicates whether the field is read-only.

**`required`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Indicates whether the field is required.

**`target`**
Type: `string`
Required: false
Default Value: `undefined`
Description: The target field item value the label should point to.

### ErrorText

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

### HelperText

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

### Input

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

### Item

#### Props

**`value`**
Type: `string`
Required: true
Default Value: `undefined`
Description: undefined

### Label

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

### RequiredIndicator

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

**`fallback`**
Type: `string | number | bigint | boolean | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | Promise<...>`
Required: false
Default Value: `undefined`
Description: undefined

### RootProvider

#### Props

**`value`**
Type: `{ ariaDescribedby: string | undefined; ids: { root: string; control: string; label: string; errorText: string; helperText: string; }; refs: { rootRef: RefObject<HTMLDivElement | null>; }; ... 11 more ...; getRequiredIndicatorProps: () => Omit<...>; }`
Required: true
Default Value: `undefined`
Description: undefined

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

### Select

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

### Textarea

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

**`autoresize`**
Type: `boolean`
Required: false
Default Value: `false`
Description: Whether the textarea should autoresize
