# Form Primitive

Form is a Starwind Runtime primitive in the field-control-coordinator contract family.
## Anatomy
### Astro
Use the Astro primitive adapter to render Form anatomy with the Runtime wiring included.
```astro
---
import { Form } from "@starwind-ui/astro/form";
---

<Form.Root>
  <Form.ErrorSummary>Please fix the highlighted fields.</Form.ErrorSummary>
</Form.Root>
```

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

export function Example() {
  return (
    <Form.Root>
      <Form.ErrorSummary>Please fix the highlighted fields.</Form.ErrorSummary>
    </Form.Root>
  );
}
```

### HTML
Render the Form data-sw-* contract yourself, then initialize createForm.
```html
<form data-sw-form data-slot="form">
  <div data-sw-form-error-summary data-slot="form-error-summary" role="status" aria-live="polite" aria-atomic="true" hidden>Please fix the highlighted fields.</div>
</form>

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

  const root = document.querySelector("[data-sw-form]");
  if (root) {
    createForm(root);
  }
</script>
```
## API Reference
### Root
The main element that owns the Form Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `form` |
| Discovery hook | `data-sw-form` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description |
| --- | --- | --- | --- | --- |
| data-error-visibility | `FormValidationTiming` | - | option | Configures the data error visibility option for the Root part. |
| data-revalidation-timing | `FormValidationTiming` | - | option | Configures the data revalidation timing option for the Root part. |
| data-validation-timing | `FormValidationTiming` | - | option | Configures the data validation timing option for the Root part. |
| errorVisibility | `FormValidationTiming` | - | option | Configures the error visibility option for the Root part. |
| revalidationTiming | `FormValidationTiming` | - | option | Configures the revalidation timing option for the Root part. |
| validationTiming | `FormValidationTiming` | - | option | Configures the validation timing option for the Root part. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-form` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-slot` | constant | `form` | Identifies Root metadata for styling and selectors. |
| `data-error-visibility` | prop | - | Reflects the error visibility prop on the Root part. |
| `data-revalidation-timing` | prop | - | Reflects the revalidation timing prop on the Root part. |
| `data-validation-timing` | prop | - | Reflects the validation timing prop on the Root part. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-form`, `data-slot`, `data-error-visibility`, `data-revalidation-timing`, `data-validation-timing` | Form must be discoverable before initialization so it can register nested Fields and preserve native form behavior. |

### Error Summary
Summary of validation errors for Form.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-form-error-summary` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-form-error-summary` | runtime | - | Marks the Error Summary part so Starwind Runtime can find it. |
| `data-slot` | constant | `form-error-summary` | Identifies Error Summary metadata for styling and selectors. |
#### Refs
| Part | Public |
| --- | --- |
| error-summary | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-form-error-summary`, `data-slot`, `role`, `aria-live`, `aria-atomic`, `hidden` | Form error summaries start hidden, expose a public part identity, and provide a polite accessible live region before the runtime renders visible errors. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createForm`](/docs/runtime/#create-form) |
| Import | `@starwind-ui/runtime/form` |
| Root part | root |
| Option props | - |
| Option lifecycles | - |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Form](/docs/components/form/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/form` | `createForm` |
| Astro Primitive | `@starwind-ui/astro/form` | `Form`, `FormRoot`, `FormErrorSummary` |
| React Primitive | `@starwind-ui/react/form` | `Form`, `FormRoot`, `FormErrorSummary` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Form` |
| runtime-factory | `createForm` |
| part | `Form.Root` |
| part | `Form.ErrorSummary` |