# Field

Field,
FieldControl,
FieldDescription,
FieldError,
FieldGroup,
FieldItem,
FieldLabel,
FieldLegend,
FieldSeparator,
FieldSet,
FieldValidity,
} from "@/components/starwind/field";

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import {
  Field,
  FieldControl,
  FieldDescription,
  FieldError,
  FieldLabel,
  FieldValidity,
} from "@/components/starwind/field";
---

<Field name="displayName">
  <FieldLabel>Display name</FieldLabel>
  <FieldControl required minlength="2" />
  <FieldDescription>This name appears on your profile.</FieldDescription>
  <FieldError match="valueMissing">Enter a display name.</FieldError>
  <FieldError match="tooShort">Use at least two characters.</FieldError>
  <FieldValidity match="valid">Looks good.</FieldValidity>
</Field>
```
  </div>
  <div slot="react">
```tsx
import {
  Field,
  FieldControl,
  FieldDescription,
  FieldError,
  FieldLabel,
  FieldValidity,
} from "@/components/starwind/field";

export function Example() {
  return (
    <Field name="displayName">
      <FieldLabel>Display name</FieldLabel>
      <FieldControl required minLength="2" />
      <FieldDescription>This name appears on your profile.</FieldDescription>
      <FieldError match="valueMissing">Enter a display name.</FieldError>
      <FieldError match="tooShort">Use at least two characters.</FieldError>
      <FieldValidity match="valid">Looks good.</FieldValidity>
    </Field>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

> **Info:** Field now coordinates native constraint validation and Runtime-backed controls. Match messages to
validity states instead of writing page-local validation listeners.

## Installation

```bash
npx starwind@latest add field
```

## Usage

### Groups and non-input controls

```astro
<FieldSet>
  <FieldLegend>Preferences</FieldLegend>
  <FieldGroup>
    <Field name="updates" orientation="horizontal">
      <FieldItem>
        <Checkbox id="field-updates" value="yes" />
        <FieldLabel for="field-updates">Product updates</FieldLabel>
      </FieldItem>
    </Field>
  </FieldGroup>
</FieldSet>
```

## Framework Availability
Field is available for Astro and React.
Astro available; React available
| Framework | Status | Notes |
| --- | --- | --- |
| Astro | available | - |
| React | available | - |
## API Reference
### Field
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `errorVisibility` | `import("@starwind-ui/runtime/form").FormValidationTiming` | No | - | Wrapper prop | Overrides when errors become visible for controls coordinated by this Field. |
| `orientation` | `"horizontal" \| "responsive" \| "vertical"` | No | `"vertical"` | Styled variant | Selects the horizontal or vertical layout direction. |
| `revalidationTiming` | `import("@starwind-ui/runtime/form").FormValidationTiming` | No | - | Wrapper prop | Selects when a previously validated field is validated again. |
| `validationTiming` | `import("@starwind-ui/runtime/form").FormValidationTiming` | No | - | Wrapper prop | Selects when validation first runs. |
- Inherits div attributes.

### FieldSet
- Inherits fieldset attributes.

### FieldLegend
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `variant` | `"label" \| "legend"` | No | `"legend"` | Styled variant | Selects the component's visual variant. |
- Inherits div attributes.

### FieldGroup
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `variant` | `"default" \| "outline"` | No | `"default"` | Styled variant | Selects the component's visual variant. |
- Inherits div attributes.

### FieldContent
- Inherits div attributes.

### FieldTitle
- Inherits div attributes.

### FieldLabel
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
- Inherits label attributes.

### FieldControl
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `defaultValue` | `string \| number \| string[]` | No | - | Wrapper prop | Sets the initial value when the component is uncontrolled. |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
| `value` | `string \| number \| string[]` | No | - | Wrapper prop | Controls or identifies the component value. |
- Inherits input attributes. Omits `children`, `defaultValue`, `size`, and `value`.

### FieldDescription
- Inherits p attributes.

### FieldError
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `match` | `boolean \| "badInput" \| "customError" \| "patternMismatch" \| "rangeOverflow" \| "rangeUnderflow" \| "stepMismatch" \| "tooLong" \| "tooShort" \| "typeMismatch" \| "valid" \| "valueMissing"` | No | - | Primitive override | Selects the validation state that renders this message. |
- Inherits div attributes.

### FieldValidity
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `match` | `boolean \| "badInput" \| "customError" \| "patternMismatch" \| "rangeOverflow" \| "rangeUnderflow" \| "stepMismatch" \| "tooLong" \| "tooShort" \| "typeMismatch" \| "valid" \| "valueMissing"` | No | - | Wrapper prop | Selects the validation state that renders this message. |
- Inherits div attributes.

### FieldItem
- Inherits div attributes.

### FieldSeparator
- Inherits div attributes.
### Primitive And Runtime API
Behavior, state, events, form participation, and imperative methods are documented in the lower-level references.
- Primitive: [Field Primitive](/docs/primitives/field/)
- Primitive: [Fieldset Primitive](/docs/primitives/fieldset/)
- Runtime factory: [`createField`](/docs/runtime/#create-field) from `@starwind-ui/runtime/field`
- Runtime factory: [`createFieldset`](/docs/runtime/#create-fieldset) from `@starwind-ui/runtime/fieldset`

## Changelog

### v1.0.0

- Added the Runtime-backed Field family with validation, grouping, labels, descriptions, and accessible messages.
- See the [Field Primitive](/docs/primitives/field/) and [Fieldset Primitive](/docs/primitives/fieldset/) for the underlying unstyled anatomy and behavior API.