Field

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

Loading...

Anatomy

<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.

Disabled

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

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.

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.

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.

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.

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.

Textarea

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

Textarea Autoresize

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

Select

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

Checkbox

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

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.

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.

API Reference

Root

Renders a <div> element.

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
disabled
boolean

Indicates whether the field is disabled.

ids
ElementIds

The ids of the field parts.

invalid
boolean

Indicates whether the field is invalid.

readOnly
boolean

Indicates whether the field is read-only.

required
boolean

Indicates whether the field is required.

target
string

The target field item value the label should point to.

ErrorText

Renders a <span> element.

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

HelperText

Renders a <span> element.

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

Input

Renders a <input> element.

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

Item

PropDefaultType
value
string

Label

Renders a <label> element.

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

RequiredIndicator

Renders a <span> element.

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
fallback
string | number | bigint | boolean | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | Promise<...>

RootProvider

Renders a <div> element.

PropDefaultType
value
{ ariaDescribedby: string | undefined; ids: { root: string; control: string; label: string; errorText: string; helperText: string; }; refs: { rootRef: RefObject<HTMLDivElement | null>; }; ... 11 more ...; getRequiredIndicatorProps: () => Omit<...>; }

asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

Select

Renders a <select> element.

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

Textarea

Renders a <textarea> element.

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
autoresizefalse
boolean

Whether the textarea should autoresize