Skip to content

Field

Stable Available in release assets

Arrange a native label, form control, persistent hint, and optional server-rendered error without owning form behavior.

Field primary example

Show code
<div class="thin-field">
  <label for="field-email">Email address</label>
  <small class="thin-hint" id="field-email-hint">Use an address like name@example.com. We’ll send order updates there.</small>
  <input class="thin-input" id="field-email" name="email" type="email" autocomplete="email" required aria-describedby="field-email-hint">
</div>

Each authored example uses the production assets and includes copyable markup.

Default field

The canonical field skin arranges a native label, control, and persistent hint.

Show code
<div class="thin-field">
  <label for="field-email">Email address</label>
  <small class="thin-hint" id="field-email-hint">Use an address like name@example.com. We’ll send order updates there.</small>
  <input class="thin-input" id="field-email" name="email" type="email" autocomplete="email" required aria-describedby="field-email-hint">
</div>

Server-rendered invalid field

The application returns an identified explanation while the native control remains the submitted value.

Show code
<div class="thin-field">
  <label for="account-email">Email address</label>
  <input id="account-email" name="email" type="email" value="invalid" aria-invalid="true" aria-describedby="account-email-hint account-email-error">
  <small class="thin-hint" id="account-email-hint">Used for account recovery.</small>
  <small class="thin-error" id="account-email-error">Enter an email address in the format name@example.com.</small>
</div>

Anatomy

  • Explicit label
  • Native input, textarea, or select
  • Optional persistent hint
  • Optional server-rendered validation error

Variants and sizes

  • Default field — shown above
  • Server-rendered invalid field — shown above

Rendered fixtures exercise authored content and constrained layouts with the same production assets.

  • Empty
  • Populated
  • Focused
  • Native invalid
  • Server-rendered invalid
  • Disabled
  • Long label and hint
  • Narrow container

Structured state fixtures are not published for this item yet.

Interaction and keyboard behavior

Field owns no JavaScript. Native input, change, constraint validation, form submission, reset, autofill, and keyboard behavior remain browser owned; server validation returns authored error content.

Accessibility

Associate an explicit label with the control, reference persistent hints and server errors with aria-describedby, and use aria-invalid only while an error is present. Keep instructions and errors in authored text rather than placeholders or color alone.

Contract
NATIVE
Basis
Native <label> and form control; no APG widget
Behavior guarantees
  • CSS only: the wrapper owns no validation, submission, reset, autofill, keyboard behavior, or control semantics.
  • A labelled native control, its hint, and a server-rendered error stay usable without Thin-Sky CSS or JavaScript.
Evidence
  • tests/unit/library/field-contract.test.ts
  • tests/browser/field-contract.spec.ts

API

Use .thin-field on a semantic wrapper. Add .thin-hint or .thin-error to authored descriptions and reference them from the native control. Optional client-side validation feedback belongs to the separate field-validation preview.

Behavior tier: css-only

Hosts

Apply the class to the HTML element that supplies the appropriate landmark or content role.

  • class="thin-field"

Custom properties

PropertyDefaultDescription
--thin-field-spacevar(--thin-space-xs)Gap between the field label, control, hint, and error.

Fallback

Without Thin-Sky CSS or JavaScript, the labelled native control, constraint validation, submission value, autocomplete, authored hint, and server-rendered error remain usable.

Assets and dependencies

  • /components.css

Dependencies: None

Source: packages/ui/src/items/field/style.ts

Stability evidence

  • CSS-only Field layout and native form-control contract: test:tests/unit/library/field-contract.test.ts
  • Complete field documentation and difficult-state evidence: test:tests/unit/library/core-components-stable.test.ts
  • Cross-theme, density, narrow-container, and localized review fixture: review:site/src/pages/quality/index.astro#quality-review

Composition

Derived from the examples and style specs, not authored.

Composes

Used by