# Form Primitive

Form coordinates native constraints, custom and asynchronous validators, schema results, error visibility, and submission across its Fields.
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 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>
```

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

<template>
  <Form.Root>
    <Form.ErrorSummary>Please fix the highlighted fields.</Form.ErrorSummary>
  </Form.Root>
</template>
```
## Validation policy values
`validationTiming`, `revalidationTiming`, and `errorVisibility` accept semantic `change`, `blur`, `submit`, or `manual` causes. `change` means each accepted value revision for native and Runtime controls. Before submission, only `validationTiming` is active; after a submission attempt, `revalidationTiming` replaces it. The defaults are `validationTiming="submit"`, `revalidationTiming="change"`, and `errorVisibility="submit"`.
## 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 | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| data-error-visibility | `"blur" \| "change" \| "manual" \| "submit"` | - | option | Low-level errorVisibility form for semantic change, blur, submit, or manual validation; defaults to submit. | - |
| data-revalidation-timing | `"blur" \| "change" \| "manual" \| "submit"` | - | option | Low-level revalidationTiming form that replaces validationTiming after a submission attempt; defaults to change. | - |
| data-validation-timing | `"blur" \| "change" \| "manual" \| "submit"` | - | option | Low-level validationTiming form for semantic change, blur, submit, or manual validation before submission; defaults to submit. | - |
| errorVisibility | `"blur" \| "change" \| "manual" \| "submit"` | submit | option | Selects whether semantic change, blur, submit, or manual validation reveals errors; defaults to submit. | - |
| revalidationTiming | `"blur" \| "change" \| "manual" \| "submit"` | change | option | After a Form submission attempt, replaces validationTiming with semantic change, blur, submit, or manual validation; defaults to change. | - |
| validationTiming | `"blur" \| "change" \| "manual" \| "submit"` | submit | option | Selects semantic change, blur, submit, or manual validation before a Form submission attempt; defaults to submit. | - |
#### 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` |
## 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.2.1
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
### v0.2.0
- Replaced additive validation timing with before- and after-submit policies and added imperative validation, visibility, reset, and external-error APIs.
- Unified the previous input and committed-only change timings as change, which now runs for every accepted value revision.
### v0.1.0
- Introduced native form coordination, validation timing, submission state, and field reset behavior.