# Field Primitive

Field is a Starwind Runtime primitive in the field-control-coordinator contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render Field anatomy with the Runtime wiring included.
```astro
---
import { Field } from "@starwind-ui/astro/field";
---

<Field.Root>
  <Field.Label>Email</Field.Label>
  <Field.Control />
  <Field.Description>Use your work email.</Field.Description>
  <Field.Error>Enter a valid email.</Field.Error>
</Field.Root>
```

### React
Use the React primitive adapter when Field state participates in React rendering.
```tsx
import { Field } from "@starwind-ui/react/field";

export function Example() {
  return (
    <Field.Root>
      <Field.Label>Email</Field.Label>
      <Field.Control />
      <Field.Description>Use your work email.</Field.Description>
      <Field.Error>Enter a valid email.</Field.Error>
    </Field.Root>
  );
}
```

### HTML
Render the Field data-sw-* contract yourself, then initialize createField.
```html
<div data-sw-field>
  <label data-sw-field-label>Email</label>
  <input data-sw-field-control data-sw-input />
  <p data-sw-field-description>Use your work email.</p>
  <div data-sw-field-error hidden>Enter a valid email.</div>
</div>

<script type="module">
  import { createField } from "@starwind-ui/runtime/field";

  const root = document.querySelector("[data-sw-field]");
  if (root) {
    createField(root);
  }
</script>
```

### Vue
Use the Vue 3.5 beta adapter to render Field anatomy.
```vue
<script setup lang="ts">
import Field from "@starwind-ui/vue/field";
</script>

<template>
  <Field.Root>
    <Field.Label>Email</Field.Label>
    <Field.Control />
    <Field.Description>Use your work email.</Field.Description>
    <Field.Error>Enter a valid email.</Field.Error>
  </Field.Root>
</template>
```
## Validation policy values
The timing props accept semantic `change`, `blur`, `submit`, or `manual` causes. Field values override the owning Form; otherwise they inherit its submit/change/submit defaults and post-submit replacement policy.
## API Reference
### Root
The main element that owns the Field Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-field` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| dirty | `boolean` | - | control | Marks whether the field value has changed. | **React:** Use dirty for controlled state.<br>**Astro:** Use dirty for initial state and call setDirty for later updates.<br>**Runtime / HTML:** call setDirty for later updates. |
| disabled | `boolean` | false | option | Disables the Root part. | - |
| data-error-visibility | `"blur" \| "change" \| "manual" \| "submit"` | - | option | Low-level errorVisibility form for semantic change, blur, submit, or manual validation; overrides the owning Form for this Field. | - |
| data-revalidation-timing | `"blur" \| "change" \| "manual" \| "submit"` | - | option | Low-level revalidationTiming form that replaces validationTiming after a submission attempt; overrides the owning Form for this Field. | - |
| data-validation-timing | `"blur" \| "change" \| "manual" \| "submit"` | - | option | Low-level validationTiming form for semantic change, blur, submit, or manual validation before submission; overrides the owning Form for this Field. | - |
| errorVisibility | `"blur" \| "change" \| "manual" \| "submit"` | submit | option | Selects whether semantic change, blur, submit, or manual validation reveals this Field's errors; inherits the owning Form policy when omitted. | - |
| invalid | `boolean` | - | control | Marks the field as invalid for validation styling and state. | - |
| name | `string` | - | option | Sets the submitted form field name. | - |
| revalidationTiming | `"blur" \| "change" \| "manual" \| "submit"` | change | option | After an owning Form submission attempt, replaces validationTiming with semantic change, blur, submit, or manual validation; inherits the owning Form policy when omitted. | - |
| touched | `boolean` | - | control | Marks whether the field has been visited. | **React:** Use touched for controlled state.<br>**Astro:** Use touched for initial state and call setTouched for later updates.<br>**Runtime / HTML:** call setTouched for later updates. |
| validationTiming | `"blur" \| "change" \| "manual" \| "submit"` | submit | option | Selects semantic change, blur, submit, or manual validation before an owning Form submission attempt; inherits the owning Form policy when omitted. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-field` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-dirty` | state | - | Reflects the dirty state on the Root part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Root part. |
| `data-error-visibility` | prop | - | Reflects the error visibility prop on the Root part. |
| `data-invalid` | state | - | Reflects the invalid state on the Root part. |
| `data-name` | prop | - | Reflects the name prop on the Root part. |
| `data-revalidation-timing` | prop | - | Reflects the revalidation timing prop on the Root part. |
| `data-touched` | state | - | Reflects the touched state on the Root part. |
| `data-validation-timing` | prop | - | Reflects the validation timing prop on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| dirty | `boolean` | dirty | - | - | - | `setDirty` | Tracks whether the Field value has changed. | **React:** Use dirty for controlled state.<br>**Astro:** Use dirty for initial state and call setDirty for later updates.<br>**Runtime / HTML:** call setDirty for later updates. |
| touched | `boolean` | touched | - | - | - | `setTouched` | Tracks whether Field has been visited. | **React:** Use touched for controlled state.<br>**Astro:** Use touched for initial state and call setTouched for later updates.<br>**Runtime / HTML:** call setTouched for later updates. |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setDirty` | prop: dirty | - | No | Updates whether Field is dirty from Runtime code. |
| `setDisabled` | prop: disabled | - | No | Updates whether Field is disabled from Runtime code. |
| `setInvalid` | prop: invalid | - | No | Updates whether Field is invalid from Runtime code. |
| `setName` | prop: name | - | No | Updates the Field form field name from Runtime code. |
| `setTouched` | prop: touched | - | No | Updates whether Field is touched from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-field`, `data-dirty`, `data-disabled`, `data-error-visibility`, `data-invalid`, `data-name`, `data-revalidation-timing`, `data-touched`, `data-validation-timing` | Field-owned control state must be available for styling and ownership before the controller attaches. |

### Label
Text label associated with Field.
| Fact | Value |
| --- | --- |
| Default element | `label` |
| Discovery hook | `data-sw-field-label` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-field-label` | runtime | - | Marks the Label part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| label | Yes |

### Control
Groups the interactive controls for Field.
| Fact | Value |
| --- | --- |
| Default element | `input` |
| Discovery hook | `data-sw-field-control` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-field-control` | runtime | - | Marks the Control part so Starwind Runtime can find it. |
| `data-sw-input` | constant | - | Identifies Control metadata for styling and selectors. |
#### Refs
| Part | Public |
| --- | --- |
| control | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-field-control`, `data-sw-input` | The generated default Field control must be discoverable as both a Field control and an Input primitive. |

### Description
Supporting description text for Field.
| Fact | Value |
| --- | --- |
| Default element | `p` |
| Discovery hook | `data-sw-field-description` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-field-description` | runtime | - | Marks the Description part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| description | Yes |

### Item
An interactive item inside the Field collection.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-field-item` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-field-item` | runtime | - | Marks the Item part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| item | Yes |

### Error
Error message content for Field.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-field-error` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| match | `FieldErrorMatch` | false | attribute | Controls how Field filters matching items. | - |
| messageSource | `"children" \| "validation"` | - | attribute | Sets the message source attribute on the Error part. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-field-error` | runtime | - | Marks the Error part so Starwind Runtime can find it. |
| `data-match` | prop | - | Reflects the match prop on the Error part. |
| `data-message-source` | prop | - | Reflects the message source prop on the Error part. |
#### Refs
| Part | Public |
| --- | --- |
| error | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-field-error`, `data-match`, `data-message-source`, `hidden` | Validation messaging starts hidden and is revealed by the Field controller. |

### Validity
Validation state container for Field.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-field-validity` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| match | `FieldErrorMatch` | true | attribute | Controls how Field filters matching items. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-field-validity` | runtime | - | Marks the Validity part so Starwind Runtime can find it. |
| `data-match` | prop | - | Reflects the match prop on the Validity part. |
#### Refs
| Part | Public |
| --- | --- |
| validity | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-field-validity`, `data-match`, `hidden` | Validity messaging starts hidden and is revealed by the Field controller. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createField`](/docs/runtime/#create-field) |
| Import | `@starwind-ui/runtime/field` |
| Root part | root |
| Option props | dirty, disabled, invalid, name, touched |
| Option lifecycles | - |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Field](/docs/components/field/) | Composite |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/field` | `createField` |
| Astro Primitive | `@starwind-ui/astro/field` | `Field`, `FieldRoot`, `FieldLabel`, `FieldControl`, `FieldDescription`, `FieldItem`, `FieldError`, `FieldValidity` |
| React Primitive | `@starwind-ui/react/field` | `Field`, `FieldRoot`, `FieldLabel`, `FieldControl`, `FieldDescription`, `FieldItem`, `FieldError`, `FieldValidity` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Field` |
| runtime-factory | `createField` |
| part | `Field.Root` |
| part | `Field.Label` |
| part | `Field.Control` |
| part | `Field.Description` |
| part | `Field.Item` |
| part | `Field.Error` |
| part | `Field.Validity` |
## Changelog
### v1.0.1
- Removed obsolete private-release warnings from generated Vue adapters and normalized the resulting blank line in vendored Primitive indexes.
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.1
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
### v0.1.0
- Introduced field labels, descriptions, validation state, and accessible message coordination.