# Field

Field,
FieldContent,
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>
  <div slot="vue">
```vue
<script setup lang="ts">
import {
  Field,
  FieldControl,
  FieldDescription,
  FieldError,
  FieldLabel,
  FieldValidity,
} from "@/components/starwind/field";
</script>

<template>
  <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>
</template>
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add field --framework astro
```
</DocsTabsContent>
```bash
npx starwind@latest add field --framework react
```
</DocsTabsContent>
```bash
npx starwind@latest add field --framework vue
```
</DocsTabsContent>
</DocsTabs>

## Usage

For complete validation policies, custom and asynchronous validation, schema adapters, and submission flows using `Field` and `FieldSet`, see the [Form examples](/docs/components/form/).

## Composition

Use `Field` for one control. Use `FieldSet` and `FieldGroup` for related controls.

```text
FieldSet
├── FieldLegend
├── FieldDescription
└── FieldGroup
    ├── Field
    │   ├── FieldLabel
    │   ├── FieldControl
    │   ├── FieldDescription
    │   ├── FieldError
    │   └── FieldValidity
    ├── FieldSeparator
    └── Field
        └── FieldItem
            ├── Checkbox or Radio
            └── FieldContent
                ├── FieldLabel
                └── FieldDescription
```

## Groups and Non-input Controls

Use `FieldSet` with `FieldLegend` when several controls answer one question or belong to the same settings section. `FieldItem` gives checkboxes, radios, and other non-text controls the same label, description, validation, disabled-state, and layout conventions as text inputs.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Checkbox } from "@/components/starwind/checkbox";
import {
  Field,
  FieldGroup,
  FieldItem,
  FieldLabel,
  FieldLegend,
  FieldSet,
} from "@/components/starwind/field";
---

<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>
```
  </div>
  <div slot="react">
```tsx
import { Checkbox } from "@/components/starwind/checkbox";
import { Field, FieldGroup, FieldItem, FieldLabel, FieldLegend, FieldSet } from "@/components/starwind/field";

export function Example() {
  return (
    <>
      <FieldSet>
        <FieldLegend>Preferences</FieldLegend>
        <FieldGroup>
          <Field name="updates" orientation="horizontal">
            <FieldItem>
              <Checkbox id="field-updates" value="yes" />
              <FieldLabel htmlFor="field-updates">Product updates</FieldLabel>
            </FieldItem>
          </Field>
        </FieldGroup>
      </FieldSet>
    </>
  );
}
```
  </div>
  <div slot="vue">
```vue
<script setup lang="ts">
import { Checkbox } from "@/components/starwind/checkbox";
import {
  Field,
  FieldGroup,
  FieldItem,
  FieldLabel,
  FieldLegend,
  FieldSet,
} from "@/components/starwind/field";
</script>

<template>
  <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>
</template>
```
  </div>
</FrameworkCodeSwitcher>

## API Reference
### Field
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `errorVisibility` | `"blur" \| "change" \| "manual" \| "submit"` | No | - | Primitive override | Selects whether semantic change, blur, submit, or manual validation reveals errors; inherits the owning Form policy when omitted. |
| `orientation` | `"horizontal" \| "responsive" \| "vertical"` | No | `"vertical"` | Styled variant | Selects the horizontal or vertical layout direction. |
| `revalidationTiming` | `"blur" \| "change" \| "manual" \| "submit"` | No | - | Primitive override | After an owning Form submission attempt, replaces validationTiming with semantic change, blur, submit, or manual validation; inherits the owning Form policy when omitted. |
| `validationTiming` | `"blur" \| "change" \| "manual" \| "submit"` | No | - | Primitive override | Selects semantic change, blur, submit, or manual validation before an owning Form submission attempt; inherits the owning Form policy when omitted. |
- 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.1

- Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

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