Anatomy

Field supports two APIs: a simple props API for common use cases and a sub-component API for advanced customization.

Simple API

1import { Field, InputField } from "@raystack/apsara";
2
3<Field label="Email" helperText="We won't share it" error={errors.email?.message}>
4  <InputField placeholder="Enter email" />
5</Field>

Sub-component API

1import { Field } from "@raystack/apsara";
2
3<Field name="email">
4  <Field.Label>Email</Field.Label>
5  <Field.Control required placeholder="Enter email" />
6  <Field.Error match="valueMissing">Email is required</Field.Error>
7  <Field.Description>We'll send a verification link</Field.Description>
8</Field>

API Reference

Root

Groups all parts of the field. Renders a <div> element.

Label

An accessible label automatically associated with the field control. Renders a <label> element.

Control

A native input element for use with the sub-component API. Renders an <input> element.

Error

An error message displayed when validation fails. Renders a <div> element.

Description

A paragraph with additional information about the field. Renders a <p> element.

Validity

Provides field validity state to a render function. Use for custom validity-based rendering.

Examples

With InputField

Use Field to add label, helper text, and error to an InputField.

1<Field label="Full Name" required helperText="As it appears on your ID">
2  <InputField placeholder="John Doe" />
3</Field>

With TextArea

Field works with TextArea the same way.

1<Field label="Bio" optional helperText="Tell us about yourself">
2  <TextArea placeholder="Write something..." />
3</Field>

With Select

Base UI-based components like Select auto-connect with Field for accessibility.

1<Field label="Country" required>
2  <Select>
3    <Select.Trigger />
4    <Select.Content>
5      <Select.Item value="us">United States</Select.Item>
6      <Select.Item value="uk">United Kingdom</Select.Item>
7      <Select.Item value="ca">Canada</Select.Item>
8    </Select.Content>
9  </Select>
10</Field>

Error State

Shows an error message and sets the invalid state on the field.

1<Field label="Email" error="Please enter a valid email address">
2  <InputField placeholder="Enter email" />
3</Field>

Helper Text

Displays additional context below the control.

1<Field label="Password" helperText="Must be at least 8 characters">
2  <InputField type="password" placeholder="Enter password" />
3</Field>

Required Field

Shows a required indicator next to the label.

1<Field label="Username" required>
2  <InputField placeholder="Enter username" />
3</Field>

Optional Field

Shows an optional indicator next to the label.

1<Field
2  label="Phone Number"
3  optional
4  helperText="We may use this for verification"
5>
6  <InputField placeholder="Enter phone number" />
7</Field>

Sub-component API

Use sub-components for Base UI native validation and custom error matching.

1<Field name="email">
2  <Field.Label>Email</Field.Label>
3  <Field.Control required type="email" placeholder="Enter email" />
4  <Field.Error match="valueMissing">Email is required</Field.Error>
5  <Field.Error match="typeMismatch">Please enter a valid email</Field.Error>
6  <Field.Description>We'll send a verification link</Field.Description>
7</Field>

Accessibility

• Field.Label automatically associates with the field control via aria-labelledby
• Field.Description automatically associates via aria-describedby
• Field.Error automatically associates error messages with the control
• Data attributes (data-invalid, data-dirty, data-touched, data-filled, data-focused) propagate to all sub-components