On this page

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

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

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

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

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>
  );
}

Render the Field data-sw-* contract yourself, then initialize createField.

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

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.

Default element: div
Discovery hook: data-sw-field
Role: -

Props

Prop Type Default

dirty boolean -

Description

Marks whether the field value has changed.

Kind

control

Targets

Full type

boolean

React

Use dirty for controlled state.

dirty

Astro

Use dirty for initial state and call setDirty for later updates.

dirty
setDirty

Runtime / HTML

call setDirty for later updates.

setDirty

disabled boolean false

Description: Disables the Root part.
Kind: option
Targets: -
Full type: boolean

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

Description: Low-level errorVisibility form for semantic change, blur, submit, or manual validation; overrides the owning Form for this Field.
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; overrides the owning Form for this Field.
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; overrides the owning Form for this Field.
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 this Field's errors; inherits the owning Form policy when omitted.
Kind: option
Targets: root
Full type: "blur" | "change" | "manual" | "submit"

invalid boolean -

Description: Marks the field as invalid for validation styling and state.
Kind: control
Targets: -
Full type: boolean

name string -

Description: Sets the submitted form field name.
Kind: option
Targets: -
Full type: string

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

Description: After an owning Form submission attempt, replaces validationTiming with semantic change, blur, submit, or manual validation; inherits the owning Form policy when omitted.
Kind: option
Targets: root
Full type: "blur" | "change" | "manual" | "submit"

touched boolean -

Description

Marks whether the field has been visited.

Kind

control

Targets

Full type

boolean

React

Use touched for controlled state.

touched

Astro

Use touched for initial state and call setTouched for later updates.

touched
setTouched

Runtime / HTML

call setTouched for later updates.

setTouched

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

Description: Selects semantic change, blur, submit, or manual validation before an owning Form submission attempt; inherits the owning Form policy when omitted.
Kind: option
Targets: root
Full type: "blur" | "change" | "manual" | "submit"

State

State Type Props

dirty boolean dirty

Description

Tracks whether the Field value has changed.

Initial attribute

Runtime getter

Runtime setter

setDirty

React

Use dirty for controlled state.

dirty

Astro

Use dirty for initial state and call setDirty for later updates.

dirty
setDirty

Runtime / HTML

call setDirty for later updates.

setDirty

touched boolean touched

Description

Tracks whether Field has been visited.

Initial attribute

Runtime getter

Runtime setter

setTouched

React

Use touched for controlled state.

touched

Astro

Use touched for initial state and call setTouched for later updates.

touched
setTouched

Runtime / HTML

call setTouched for later updates.

setTouched

Data Attributes

Runtime hooks

Attribute Value Description

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

State

Attribute Value Description

data-dirty - Reflects the dirty state on the Root part.

data-invalid - Reflects the invalid state on the Root part.

data-touched - Reflects the touched state on the Root part.

Metadata

Attribute Value Description

data-disabled - Reflects the disabled prop on the Root part.

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

data-name - Reflects the name 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.

Label

Text label associated with Field.

Default element: label
Discovery hook: data-sw-field-label
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-field-label - Marks the Label part so Starwind Runtime can find it.

Control

Groups the interactive controls for Field.

Default element: input
Discovery hook: data-sw-field-control
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-field-control - Marks the Control part so Starwind Runtime can find it.

Metadata

Attribute Value Description

data-sw-input - Identifies Control metadata for styling and selectors.

Description

Supporting description text for Field.

Default element: p
Discovery hook: data-sw-field-description
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-field-description - Marks the Description part so Starwind Runtime can find it.

Item

An interactive item inside the Field collection.

Default element: div
Discovery hook: data-sw-field-item
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-field-item - Marks the Item part so Starwind Runtime can find it.

Error

Error message content for Field.

Default element: div
Discovery hook: data-sw-field-error
Role: -

Props

Prop Type Default

match FieldErrorMatch false

Description: Controls how Field filters matching items.
Kind: attribute
Targets: error
Full type: FieldErrorMatch

messageSource "children" | "validation" -

Description: Sets the message source attribute on the Error part.
Kind: attribute
Targets: error
Full type: "children" | "validation"

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-field-error - Marks the Error part so Starwind Runtime can find it.

Metadata

Attribute Value Description

data-match - Reflects the match prop on the Error part.

data-message-source - Reflects the message source prop on the Error part.

Validity

Validation state container for Field.

Default element: div
Discovery hook: data-sw-field-validity
Role: -

Props

Prop Type Default

match FieldErrorMatch true

Description: Controls how Field filters matching items.
Kind: attribute
Targets: validity
Full type: FieldErrorMatch

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-field-validity - Marks the Validity part so Starwind Runtime can find it.

Metadata

Attribute Value Description

data-match - Reflects the match prop on the Validity part.

Runtime API

Factory: createField
Import: @starwind-ui/runtime/field
Root hook: root data-sw-field
Option props: dirty, disabled, invalid, name, touched

Runtime Setters

Method Target Description

setDirty prop: dirty Updates whether Field is dirty from Runtime code.

setDisabled prop: disabled Updates whether Field is disabled from Runtime code.

setInvalid prop: invalid Updates whether Field is invalid from Runtime code.

setName prop: name Updates the Field form field name from Runtime code.

setTouched prop: touched Updates whether Field is touched from Runtime code.

Component Relationship

Field Composite

Changelog

View version history v1.0.0 3 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.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.

Layer Metadata

Field Primitive uses createField. Styled components: Field.

primitive Field Primitive Field Primitive uses createField. Styled components: Field. Runtime primitive Primitive adapter Astro Primitive adapters React Primitive adapters field Field Field Control Coordinator Primitives that coordinate field metadata, validity, and messages. /docs/primitives/field/ createField @starwind-ui/runtime/field /docs/runtime/#create-field root dirty disabled invalid name touched raw-html astro react solid svelte vue HTML Astro React Solid Svelte Vue Raw HTML Render the Field data-sw-* contract yourself, then initialize createField. html Use the Astro primitive adapter to render Field anatomy with the Runtime wiring included. Use the React primitive adapter when Field state participates in React rendering. tsx div data-sw-field boolean Marks whether the field value has changed. Disables the Root part. data-error-visibility "blur" | "change" | "manual" | "submit" FormValidationTiming Low-level errorVisibility form for semantic change, blur, submit, or manual validation; overrides the owning Form for this Field. data-revalidation-timing Low-level revalidationTiming form that replaces validationTiming after a submission attempt; overrides the owning Form for this Field. data-validation-timing Low-level validationTiming form for semantic change, blur, submit, or manual validation before submission; overrides the owning Form for this Field. errorVisibility Selects whether semantic change, blur, submit, or manual validation reveals this Field's errors; inherits the owning Form policy when omitted. Marks the field as invalid for validation styling and state. string Sets the submitted form field name. revalidationTiming After an owning Form submission attempt, replaces validationTiming with semantic change, blur, submit, or manual validation; inherits the owning Form policy when omitted. Marks whether the field has been visited. validationTiming Selects semantic change, blur, submit, or manual validation before an owning Form submission attempt; inherits the owning Form policy when omitted. 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. Reflects the error visibility prop on the Root part. data-invalid Reflects the invalid state on the Root part. data-name Reflects the name prop on the Root part. Reflects the revalidation timing prop on the Root part. data-touched Reflects the touched state on the Root part. Reflects the validation timing prop on the Root part. setDirty setTouched setDisabled setInvalid setName label data-sw-field-label Marks the Label part so Starwind Runtime can find it. control input data-sw-field-control Marks the Control part so Starwind Runtime can find it. data-sw-input constant Identifies Control metadata for styling and selectors. description p data-sw-field-description Marks the Description part so Starwind Runtime can find it. item data-sw-field-item Marks the Item part so Starwind Runtime can find it. error data-sw-field-error match FieldErrorMatch Controls how Field filters matching items. messageSource "children" | "validation" Sets the message source attribute on the Error part. Marks the Error part so Starwind Runtime can find it. data-match Reflects the match prop on the Error part. data-message-source Reflects the message source prop on the Error part. validity data-sw-field-validity Marks the Validity part so Starwind Runtime can find it. Reflects the match prop on the Validity part. Root Label Control Description Item Error hidden Validity @starwind-ui/astro @starwind-ui/astro/field Render initial Field state attributes and let the runtime controller own subsequent coordination. @starwind-ui/react @starwind-ui/react/field Bridge root prop updates through Field setter methods without recreating the controller. /docs/components/field/ Composite composite The styled field layer combines field and fieldset primitives. Styled component Field

Field Primitive

Anatomy

Validation policy values

API Reference

Root

Props

State

Data Attributes

Runtime hooks

State

Metadata

Label

Data Attributes

Runtime hooks

Control

Data Attributes

Runtime hooks

Metadata

Description

Data Attributes

Runtime hooks

Item

Data Attributes

Runtime hooks

Error

Props

Data Attributes

Runtime hooks

Metadata

Validity

Props

Data Attributes

Runtime hooks

Metadata

Runtime API

Runtime Setters

Related Styled Components

Changelog

v1.0.0

v0.1.1

v0.1.0