On this page

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

Use the Astro primitive adapter to render Form anatomy with the Runtime wiring included.

---
import { Form } from "@starwind-ui/astro/form";
---

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

Use the React primitive adapter when Form state participates in React rendering.

import { Form } from "@starwind-ui/react/form";

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

Render the Form data-sw-* contract yourself, then initialize createForm.

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

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.

Default element: form
Discovery hook: data-sw-form
Role: -

Props

Prop Type Default

data-error-visibility "blur" | "change" | "manual" | "submit" -

Description: Low-level errorVisibility form for semantic change, blur, submit, or manual validation; defaults to submit.
Kind: option
Targets: root
Full type: "blur" | "change" | "manual" | "submit"

data-revalidation-timing "blur" | "change" | "manual" | "submit" -

Description: Low-level revalidationTiming form that replaces validationTiming after a submission attempt; defaults to change.
Kind: option
Targets: root
Full type: "blur" | "change" | "manual" | "submit"

data-validation-timing "blur" | "change" | "manual" | "submit" -

Description: Low-level validationTiming form for semantic change, blur, submit, or manual validation before submission; defaults to submit.
Kind: option
Targets: root
Full type: "blur" | "change" | "manual" | "submit"

errorVisibility "blur" | "change" | "manual" | "submit" submit

Description: Selects whether semantic change, blur, submit, or manual validation reveals errors; defaults to submit.
Kind: option
Targets: root
Full type: "blur" | "change" | "manual" | "submit"

revalidationTiming "blur" | "change" | "manual" | "submit" change

Description: After a Form submission attempt, replaces validationTiming with semantic change, blur, submit, or manual validation; defaults to change.
Kind: option
Targets: root
Full type: "blur" | "change" | "manual" | "submit"

validationTiming "blur" | "change" | "manual" | "submit" submit

Description: Selects semantic change, blur, submit, or manual validation before a Form submission attempt; defaults to submit.
Kind: option
Targets: root
Full type: "blur" | "change" | "manual" | "submit"

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-form - Marks the Root part so Starwind Runtime can find it.

Metadata

Attribute Value Description

data-slot form Identifies Root metadata for styling and selectors.

data-error-visibility - Reflects the error visibility prop on the Root part.

data-revalidation-timing - Reflects the revalidation timing prop on the Root part.

data-validation-timing - Reflects the validation timing prop on the Root part.

Error Summary

Summary of validation errors for Form.

Default element: div
Discovery hook: data-sw-form-error-summary
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-form-error-summary - Marks the Error Summary part so Starwind Runtime can find it.

Metadata

Attribute Value Description

data-slot form-error-summary Identifies Error Summary metadata for styling and selectors.

Runtime API

Factory: createForm
Import: @starwind-ui/runtime/form
Root hook: root data-sw-form
Option props: -

Component Relationship

Form Direct primitive

Changelog

View version history v1.0.0 4 releases

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.

Layer Metadata

Form Primitive uses createForm. Styled components: Form.

primitive Form Primitive Form Primitive uses createForm. Styled components: Form. Runtime primitive Primitive adapter Astro Primitive adapters React Primitive adapters form Form Field Control Coordinator Primitives that coordinate field metadata, validity, and messages. /docs/primitives/form/ createForm @starwind-ui/runtime/form /docs/runtime/#create-form root raw-html astro react solid svelte vue HTML Astro React Solid Svelte Vue Raw HTML Render the Form data-sw-* contract yourself, then initialize createForm. html Use the Astro primitive adapter to render Form anatomy with the Runtime wiring included. Use the React primitive adapter when Form state participates in React rendering. tsx data-sw-form data-error-visibility "blur" | "change" | "manual" | "submit" FormValidationTiming Low-level errorVisibility form for semantic change, blur, submit, or manual validation; defaults to submit. data-revalidation-timing Low-level revalidationTiming form that replaces validationTiming after a submission attempt; defaults to change. data-validation-timing Low-level validationTiming form for semantic change, blur, submit, or manual validation before submission; defaults to submit. errorVisibility Selects whether semantic change, blur, submit, or manual validation reveals errors; defaults to submit. revalidationTiming After a Form submission attempt, replaces validationTiming with semantic change, blur, submit, or manual validation; defaults to change. validationTiming Selects semantic change, blur, submit, or manual validation before a Form submission attempt; defaults to submit. runtime Marks the Root part so Starwind Runtime can find it. data-slot constant Identifies Root metadata for styling and selectors. prop Reflects the error visibility prop on the Root part. Reflects the revalidation timing prop on the Root part. Reflects the validation timing prop on the Root part. error-summary div data-sw-form-error-summary Marks the Error Summary part so Starwind Runtime can find it. form-error-summary Identifies Error Summary metadata for styling and selectors. Root Error Summary role aria-live aria-atomic hidden @starwind-ui/astro @starwind-ui/astro/form Render a real form element and let the runtime register nested Fields without preventing valid native submission. Retrieve the idempotent imperative controller with createForm(element); the component does not expose a controller ref. @starwind-ui/react @starwind-ui/react/form Create the Form runtime once for the real form element and clean it up on unmount. Keep the public ref on the HTMLFormElement; retrieve the idempotent imperative controller with createForm(element). /docs/components/form/ Direct primitive direct-primitive Styled component Form

Form Primitive

Anatomy

Validation policy values

API Reference

Root

Props

Data Attributes

Runtime hooks

Metadata

Error Summary

Data Attributes

Runtime hooks

Metadata

Runtime API

Related Styled Components

Changelog

v1.0.0

v0.2.1

v0.2.0

v0.1.0