Field

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, Input } from "@raystack/apsara";
2
3<Field label="Email" description="We won't share it" error={errors.email?.message}>
4  <Input 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>

Usage

Field wraps a control and wires its label, description and error message to it. It works the same way whichever control goes inside.

With Input

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

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

With TextArea

Field wraps a TextArea the same way it wraps an Input — the label, description, and error all wire up through the same context.

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  <Input 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  <Input type="password" placeholder="Enter password" />
3</Field>

Required Field

Shows a required indicator next to the label.

1<Field label="Username" required>
2  <Input 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  <Input 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>

API Reference

The control sits in a root; the label, description and error attach to it.

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.

Slots

Every rendered part carries a stable data-slot attribute for styling and testing:

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