On this page

Field Primitive

Field is a Starwind Runtime primitive in the field-control-coordinator contract family.

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>

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

disabled boolean false

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

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

touched boolean -

Description: Marks whether the field has been visited.
Kind: control
Targets: -
Full type: boolean

State

State Type Props

dirty boolean dirty

Description: Tracks whether the Field value has changed.
Initial attribute: -
Runtime getter: -
Runtime setter: setDirty
State control support: 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

Description: Tracks whether Field has been visited.
Initial attribute: -
Runtime getter: -
Runtime setter: setTouched
State control support: 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.

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

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. Marks the field as invalid for validation styling and state. string Sets the submitted form field name. Marks whether the field has been visited. 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 Reflects the invalid state on the Root part. data-name Reflects the name prop on the Root part. data-touched Reflects the touched state 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

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