Anatomy

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

Simple API

Use label, description, and error props for quick forms or when validation is handled externally (e.g., React Hook Form).

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

Sub-component API

Use sub-components for built-in constraint validation with Field.Control and Field.Error match="...". This uses native HTML validation attributes and shows targeted error messages.

1import { Field } from "@raystack/apsara";
2
3<Field name="email">
4  <Field.Label>Email</Field.Label>
5  <Field.Control required type="email" placeholder="Enter email" />
6  <Field.Error match="valueMissing">Email is required</Field.Error>
7  <Field.Error match="typeMismatch">Enter a valid email address</Field.Error>
8  <Field.Description>We'll send a verification link</Field.Description>
9</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. Supports standard HTML validation attributes: required, type, pattern, minLength, maxLength, min, max, step.

Error

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

The match prop controls when the error is shown:

• match="valueMissing" — shown when a required field is empty
• match="typeMismatch" — shown when type="email" or type="url" value is invalid
• match="patternMismatch" — shown when value doesn't match the pattern regex
• match="tooShort" / match="tooLong" — shown for minLength / maxLength violations
• match="rangeUnderflow" / match="rangeOverflow" — shown for min / max violations
• match="customError" — shown when the Field's validate prop returns an error

Description

A paragraph with additional information about the field. Renders a <p> element. Hidden when an error is present (in the simple API).

Validity

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

Examples

With InputField

Use Field to add label, description, and error to an InputField.

1<Field label="Full Name" required description="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" required={false} description="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

Pass an error string to show the error message and set the field to invalid state. The description is hidden while an error is shown.

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

Constraint Validation Errors

Use Field.Control with native attributes and multiple Field.Error elements to show targeted messages for each validation constraint.

1<Field name="password">
2  <Field.Label>Password</Field.Label>
3  <Field.Control
4    type="password"
5    required
6    minLength={8}
7    placeholder="Create a password"
8  />
9  <Field.Error match="valueMissing">Password is required</Field.Error>
10  <Field.Error match="tooShort">Must be at least 8 characters</Field.Error>
11  <Field.Description>Minimum 8 characters</Field.Description>
12</Field>

Custom Validation

Use the validate prop to run custom logic. Return an error string to fail, or null to pass. The error renders via Field.Error match="customError".

1<Field
2  name="slug"
3  validate={(value) => {
4    if (!value) return "Slug is required";
5    if (!/^[a-z0-9-]+$/.test(String(value)))
6      return "Only lowercase letters, numbers, and hyphens";
7    return null;
8  }}
9>
10  <Field.Label>URL Slug</Field.Label>
11  <Field.Control required placeholder="my-page-slug" />
12  <Field.Error match="customError" />
13</Field>

Description

Displays additional context below the control.

1<Field label="Password" description="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

Set required={false} to show an "(optional)" indicator next to the label.

1<Field
2  label="Phone Number"
3  required={false}
4  description="We may use this for verification"
5>
6  <InputField placeholder="Enter phone number" />
7</Field>

Sub-component API

Use sub-components for built-in constraint validation with 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
• When used inside a Form, the field participates in form-level validation