On this page

Field

Display name

This name appears on your public profile.

---
import {
  Field,
  FieldControl,
  FieldDescription,
  FieldError,
  FieldLabel,
  FieldValidity,
} from "@/components/starwind/field";
---

<Field name="displayName">
  <FieldLabel>Display name</FieldLabel>
  <FieldControl required minlength="2" />
  <FieldDescription>This name appears on your profile.</FieldDescription>
  <FieldError match="valueMissing">Enter a display name.</FieldError>
  <FieldError match="tooShort">Use at least two characters.</FieldError>
  <FieldValidity match="valid">Looks good.</FieldValidity>
</Field>

import {
  Field,
  FieldControl,
  FieldDescription,
  FieldError,
  FieldLabel,
  FieldValidity,
} from "@/components/starwind/field";

export function Example() {
  return (
    <Field name="displayName">
      <FieldLabel>Display name</FieldLabel>
      <FieldControl required minLength="2" />
      <FieldDescription>This name appears on your profile.</FieldDescription>
      <FieldError match="valueMissing">Enter a display name.</FieldError>
      <FieldError match="tooShort">Use at least two characters.</FieldError>
      <FieldValidity match="valid">Looks good.</FieldValidity>
    </Field>
  );
}

Runtime example adjustment

Field now coordinates native constraint validation and Runtime-backed controls. Match messages to validity states instead of writing page-local validation listeners.

Installation

pnpx starwind@latest add field

npx starwind@latest add field

yarn dlx starwind@latest add field

Framework Availability

Astro Available React Available

Field is available for Astro and React.

Usage

Groups and non-input controls

Preferences

Product updates

Receive occasional release notes.

<FieldSet>
  <FieldLegend>Preferences</FieldLegend>
  <FieldGroup>
    <Field name="updates" orientation="horizontal">
      <FieldItem>
        <Checkbox id="field-updates" value="yes" />
        <FieldLabel for="field-updates">Product updates</FieldLabel>
      </FieldItem>
    </Field>
  </FieldGroup>
</FieldSet>

API Reference

Styled Component API

These props are added or materially changed by the installed Astro styled component. Standard HTML attributes remain available through the inherited interfaces noted below. Follow the Primitive and Runtime links for lower-level behavior props.

Field

Inherits div attributes.

Contains the following additional props:

Prop Type Default

errorVisibility import("@starwind-ui/runtime/form").FormValidationTiming —

Description: Overrides when errors become visible for controls coordinated by this Field.
Classification: Wrapper prop

orientation "horizontal" | "responsive" | "vertical" "vertical"

Description: Selects the horizontal or vertical layout direction.
Classification: Styled variant

revalidationTiming import("@starwind-ui/runtime/form").FormValidationTiming —

Description: Selects when a previously validated field is validated again.
Classification: Wrapper prop

validationTiming import("@starwind-ui/runtime/form").FormValidationTiming —

Description: Selects when validation first runs.
Classification: Wrapper prop

Field Legend

Inherits div attributes.

Contains the following additional props:

Prop Type Default

variant "label" | "legend" "legend"

Description: Selects the component's visual variant.
Classification: Styled variant

Field Group

Inherits div attributes.

Contains the following additional props:

Prop Type Default

variant "default" | "outline" "default"

Description: Selects the component's visual variant.
Classification: Styled variant

Field Label

Inherits label attributes.

Contains the following additional props:

Prop Type Default

size "sm" | "md" | "lg" "md"

Description: Selects the component's visual size.
Classification: Styled variant

Field Control

Inherits input attributes. Omits `children`, `defaultValue`, `size`, and `value`.

Contains the following additional props:

Prop Type Default

defaultValue string | number | string[] —

Description: Sets the initial value when the component is uncontrolled.
Classification: Wrapper prop

size "sm" | "md" | "lg" "md"

Description: Selects the component's visual size.
Classification: Styled variant

value string | number | string[] —

Description: Controls or identifies the component value.
Classification: Wrapper prop

Field Error

Inherits div attributes.

Contains the following additional props:

Prop Type Default

match

boolean | "badInput" | "customError" | "patternMismatch" | "rangeOverflow" | "rangeUnderflow" | "stepMismatch" | "tooLong" | "tooShort" | "typeMismatch" | "valid" | "valueMissing"

—

Description: Selects the validation state that renders this message.
Classification: Primitive override
Primitive prop: field.Error.match

Field Validity

Inherits div attributes.

Contains the following additional props:

Prop Type Default

match

boolean | "badInput" | "customError" | "patternMismatch" | "rangeOverflow" | "rangeUnderflow" | "stepMismatch" | "tooLong" | "tooShort" | "typeMismatch" | "valid" | "valueMissing"

—

Description: Selects the validation state that renders this message.
Classification: Wrapper prop

Primitive And Runtime API

Use these references when you need the lower-level behavior APIs behind Field.

Primitive API

Runtime API

Field primitive: createField from @starwind-ui/runtime/field
Fieldset primitive: createFieldset from @starwind-ui/runtime/fieldset

Changelog

v1.0.0

Added the Runtime-backed Field family with validation, grouping, labels, descriptions, and accessible messages.
See the Field Primitive and Fieldset Primitive for the underlying unstyled anatomy and behavior API.

Layer Metadata

Field combines multiple primitives: Field and Fieldset. Field is available for Astro and React.

styled-component Field Field combines multiple primitives: Field and Fieldset. Field is available for Astro and React. Styled component Behavior Foundation field composite Composite The styled field layer combines field and fieldset primitives. /docs/components/field/ FieldContent FieldControl FieldDescription FieldError FieldGroup FieldItem FieldLabel FieldLegend FieldSeparator FieldSet FieldTitle FieldValidity Content Control Description Error Group Item Label Legend Root Separator Set Title Validity FieldVariants fieldset Fieldset Form & Input forms inputs controls astro react fieldContent fieldControl fieldDescription fieldError fieldGroup fieldItem fieldLabel fieldLegend fieldSeparator fieldSeparatorContent fieldSet fieldTitle fieldValidity field-content field-control field-description field-error field-group field-item field-label field-legend field-separator field-separator-content field-set field-title field-validity /docs/primitives/field/ Primitive Field /docs/primitives/fieldset/ Primitive Fieldset createField @starwind-ui/runtime/field /docs/runtime/#create-field Runtime factory createField createFieldset @starwind-ui/runtime/fieldset /docs/runtime/#create-fieldset Runtime factory createFieldset Astro available Available Astro available React React available errorVisibility import("@starwind-ui/runtime/form").FormValidationTiming Wrapper prop Overrides when errors become visible for controls coordinated by this Field. orientation "horizontal" | "responsive" | "vertical" Styled variant "vertical" Selects the horizontal or vertical layout direction. horizontal responsive vertical revalidationTiming Selects when a previously validated field is validated again. validationTiming Selects when validation first runs. div attributes fieldset attributes variant "label" | "legend" "legend" Selects the component's visual variant. label legend "default" | "outline" "default" default outline size "sm" | "md" | "lg" "md" Selects the component's visual size. sm md lg label attributes defaultValue string | number | string[] Sets the initial value when the component is uncontrolled. value Controls or identifies the component value. input attributes p attributes match boolean | "badInput" | "customError" | "patternMismatch" | "rangeOverflow" | "rangeUnderflow" | "stepMismatch" | "tooLong" | "tooShort" | "typeMismatch" | "valid" | "valueMissing" Primitive override Selects the validation state that renders this message.