# Field Primitive

Field is a Starwind Runtime primitive in the field-control-coordinator contract family.
## 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>
```
## 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 |
| --- | --- | --- | --- | --- |
| dirty | `boolean` | - | control | Marks whether the field value has changed. |
| disabled | `boolean` | false | option | Disables the Root part. |
| invalid | `boolean` | - | control | Marks the field as invalid for validation styling and state. |
| name | `string` | - | option | Sets the submitted form field name. |
| touched | `boolean` | - | control | Marks whether the field has been visited. |
#### 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-invalid` | state | - | Reflects the invalid state on the Root part. |
| `data-name` | prop | - | Reflects the name prop on the Root part. |
| `data-touched` | state | - | Reflects the touched state 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 supports controlled state with the dirty prop. Runtime/HTML updates with setDirty. Astro adapters render initial/default state, but do not expose reactive controlled-state props for this state. |
| touched | `boolean` | touched | - | - | - | `setTouched` | Tracks whether Field has been visited. | React supports controlled state with the touched prop. Runtime/HTML updates with setTouched. Astro adapters render initial/default state, but do not expose reactive controlled-state props for this state. |
#### 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-invalid`, `data-name`, `data-touched` | 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 |
| --- | --- | --- | --- | --- |
| 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 |
| --- | --- | --- | --- | --- |
| 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` |