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

Installation

pnpx starwind@latest add field

npx starwind@latest add field

yarn dlx starwind@latest add field

Usage

For complete validation policies, custom and asynchronous validation, schema adapters, and submission flows using Field and FieldSet, see the Form examples.

Groups and non-input controls

Use FieldSet with FieldLegend when several controls answer one question or belong to the same settings section. FieldItem gives checkboxes, radios, and other non-text controls the same label, description, validation, disabled-state, and layout conventions as text inputs.

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>

import { Checkbox } from "@/components/starwind/checkbox";
import { Field, FieldGroup, FieldItem, FieldLabel, FieldLegend, FieldSet } from "@/components/starwind/field";

export function Example() {
  return (
    <>
      <FieldSet>
        <FieldLegend>Preferences</FieldLegend>
        <FieldGroup>
          <Field name="updates" orientation="horizontal">
            <FieldItem>
              <Checkbox id="field-updates" value="yes" />
              <FieldLabel htmlFor="field-updates">Product updates</FieldLabel>
            </FieldItem>
          </Field>
        </FieldGroup>
      </FieldSet>
    </>
  );
}

API Reference

Styled Component API

These props are added or materially changed by the installed styled component. Standard HTML attributes remain available through the inherited interfaces noted below. Expand a prop to see named type definitions and framework-specific imports. Follow the Primitive and Runtime links for lower-level behavior props.

Field

Inherits div attributes.

Contains the following additional props:

Prop Type Default

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

Description: Selects whether semantic change, blur, submit, or manual validation reveals errors; inherits the owning Form policy when omitted.
Classification: Primitive override
Primitive prop: field.Root.errorVisibility

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

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

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

Description: After an owning Form submission attempt, replaces validationTiming with semantic change, blur, submit, or manual validation; inherits the owning Form policy when omitted.
Classification: Primitive override
Primitive prop: field.Root.revalidationTiming

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

Description: Selects semantic change, blur, submit, or manual validation before an owning Form submission attempt; inherits the owning Form policy when omitted.
Classification: Primitive override
Primitive prop: field.Root.validationTiming

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
Type imports: React import type { InputValue } from "@starwind-ui/react";

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
Type imports: React import type { InputValue } from "@starwind-ui/react";

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

Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

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 "blur" | "change" | "manual" | "submit" Primitive override Selects whether semantic change, blur, submit, or manual validation reveals errors; inherits the owning Form policy when omitted. orientation "horizontal" | "responsive" | "vertical" Styled variant "vertical" Selects the horizontal or vertical layout direction. horizontal responsive vertical revalidationTiming After an owning Form submission attempt, replaces validationTiming with semantic change, blur, submit, or manual validation; inherits the owning Form policy when omitted. validationTiming Selects semantic change, blur, submit, or manual validation before an owning Form submission attempt; inherits the owning Form policy when omitted. 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[] import type { InputValue } from "@starwind-ui/react"; Wrapper prop 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" Selects the validation state that renders this message.