Fields & selection

Field family / style helpers

Composable labels, hints, text controls, and style helpers for consistent form fields.

FieldGroupFieldLabelFieldLegendFieldHintTextInputTextAreafieldGroupStylesfieldLabelStylesfieldLegendStylesfieldHintStylesinputStyles

View source

Component workbench

Configure the production component, inspect it at responsive widths, copy synchronized JSX, and share the exact state from one workspace.

We will never share it.

Generated example

This JSX stays synchronized with the controls and uses only public package APIs.

tsx

'use client';

import { useId } from 'react';
import { FieldGroup, FieldHint, FieldLabel, TextInput } from '@ai-created/ui';

export function Example() {
  const hintId = useId();

  return (
    <FieldGroup>
      <FieldLabel htmlFor="example-field">{"Email"}</FieldLabel>
      <TextInput
        id="example-field"
        aria-describedby={hintId}
        placeholder="Enter a value"
      />
      <FieldHint id={hintId}>{"We will never share it."}</FieldHint>
    </FieldGroup>
  );
}

Import

tsx

import { FieldGroup, FieldLabel, FieldHint, TextInput, TextArea } from '@ai-created/ui';

Client boundary

Add 'use client' to the file that owns this interactive state.

Install from a reviewed release

Replace the version placeholder with the release tag your product has reviewed.

shell

npm install --install-links "git+https://github.com/TheMarco/ai-created-ui.git#vX.Y.Z"

Load semantic tokens

css

@import '@ai-created/ui/styles/tokens.css';

@tailwind base;
@tailwind components;
@tailwind utilities;

Extend Tailwind

module.exports = {
  presets: [require('@ai-created/ui/tailwind-preset')],
  content: [
    './src/**/*.{js,ts,jsx,tsx,mdx}',
    './node_modules/@ai-created/ui/src/**/*.{js,ts,jsx,tsx}',
  ],
};

Anatomy

Named regions define what belongs to the component, what remains optional, and where semantic responsibility lives.

Field group

Required

Layout wrapper for one logical field.

div

Label

Required

Visible name associated to the control.

label

Control

Required

Native input or textarea.

input / textarea

Hint

Optional

Optional help or validation message associated by id.

p

Visual legend

Optional

Optional uppercase group caption; not a semantic legend.

span

Construction and authoring

The Figma-equivalent asset model, auto-layout, resizing, properties, slots, content bounds, localization, and governance contract.

Asset kind

component

Design library name

Components/Forms/Field

Maturity

stable

Last reviewed

2026-08-29

Canvas applicability

Publish a nested field component with input and textarea instance swaps plus state properties.

Auto layout

Direction: vertical
Gap: 8px
Padding: 0px
Alignment: Stretch
Wrap: Content wraps

FieldGroup owns the sibling gap; FieldLabel, FieldLegend, controls, and FieldHint do not add exterior spacing.

Resizing

Width: fill
Height: hug
Minimum width: 160px
Maximum width: Parent controlled
Minimum height: 44px plus labels and hints
Maximum height: Content controlled
Overflow: visible

Exposed design properties

Property	Type	Default	Code mapping	Options or notes
Control	instance-swap	TextInput	TextInput or TextArea child	TextInput, TextArea
LabelRequired	text	Label	FieldLabel children	No additional constraint
Hint or error	text	None	FieldHint children	No additional constraint
Disabled	boolean	false	disabled on the native control	No additional constraint
Invalid	boolean	false	aria-invalid on the native control plus semantic hint content	No additional constraint
Required	boolean	false	required on the native control and a localized label indicator	No additional constraint

Nested assets and slots

FieldGroup

primitive / required

Vertical field composition root.

FieldGroup

FieldLabel

subcomponent / required

Visible native label.

FieldLabel

Control

slot / required

TextInput, TextArea, or an equivalent labelled control.

TextInput, TextArea, or styled custom control

FieldHint

subcomponent

Description, requirement, or validation message.

FieldHint

Content limits

Label

One concise line preferred

Overflow: Allow wrap, never truncate.

Every field needs an unambiguous name.

Hint or error

One or two short sentences

Overflow: Move extended help outside the field.

Immediate guidance should be scannable.

Text area

Default visible size should cover the expected response, then grow or scroll

Overflow: Use a counter or explicit maximum for constrained data.

Input size communicates expected content.

Localization and RTL

Translatable: Label, Placeholder, Hint, Validation message

Text and control direction follow the locale or the entered data type.
Required indicators stay next to the logical end of the label.
Test labels at twice English length.
Test mixed-direction user input.
Test errors at 200% text size.

Responsive behavior

Fill its form column.

No internal breakpoint

Parent form controls column count.
Never reduce the control below 160px unless the data format explicitly allows it.

Authoring limits

Figma properties cannot guarantee label, hint, and control ID associations.
Consumers must connect htmlFor, id, aria-describedby, required, and aria-invalid correctly.

Accountable owner

Design systems form foundations owner

Canonical source: src/components/Field.tsx

New field primitives require form accessibility and validation-pattern review.
A breaking property, token, or behavior change requires design and engineering approval, a migration note, and a major release.
The design asset, implementation, documentation, accessibility contract, and regression coverage must ship in the same change.

Read the system construction standard

Visual specification

These measurements and semantic tokens define the supported visual contract. Local overrides should preserve the same hierarchy and interaction cues.

FieldGroup sibling gap

8px

Label, legend, and hint exterior margin

0px

Input padding

16px horizontal / 12px vertical

Input radius

6px

Input border

1px

Rules

FieldGroup is the single owner of vertical spacing between its label, control, and optional hint.
Keep labels persistently visible; placeholders are examples, not labels.
Apply validation meaning and relationships in consuming code.
TextArea disables manual resizing by default.

Token dependencies

--color-surface2

Control background.

--color-control-border / --color-control-border-strong

Contrast-safe default and hover boundaries.

--color-accent

Focused border.

--color-text / --color-text2 / --color-text3

Value, label/help, and placeholder hierarchy.

--radius-md

Control radius.

States and behavior

A component is not complete until its passive, interactive, disabled, and exceptional states remain understandable in both themes.

default

Trigger: Idle enabled field.
Visual response: Surface2 fill, standard border, primary value, secondary label.
Behavior: Native text editing.

focus-visible

Trigger: Keyboard focus enters the control.
Visual response: Global focus outline plus accent border.
Behavior: Accepts keyboard input.

disabled

Trigger: Native disabled is set.
Visual response: 50% opacity and not-allowed cursor.
Behavior: Editing and focus are suppressed.

invalid

Trigger: Consumer sets aria-invalid and error styling/content.
Visual response: Consumer must add a clear error treatment.
Behavior: Validation message explains correction.
Accessibility: aria-invalid and aria-describedby connect the error.

Accessibility contract

Semantics, accessible naming, keyboard behavior, focus and announcements are implementation requirements, not optional documentation.

Semantics: Native label, input, textarea, and paragraph primitives; FieldGroup and FieldLegend are presentation-only.
Accessible name: Associate FieldLabel with the control using htmlFor/id, or nest the control.

Connect FieldHint and validation errors with aria-describedby.
Set aria-invalid when validation fails.
Use a real fieldset and legend for grouped choices; FieldLegend is only a styled span.
Preserve native autocomplete, inputMode, type, and name attributes.

Keyboard behavior

Tab / Shift+Tab: Moves focus into or out of the control.
Standard text editing keys: Edit, select, undo, and navigate text according to the native platform.

Implementation

Use the public package API and preserve the controlled-state, native-attribute, and ref contracts described below.

tsx

import { FieldGroup, FieldLabel, FieldHint, TextInput, TextArea } from '@ai-created/ui';

Client Component required

Every primitive forwards its native ref and attributes.
FieldGroup owns the 8px sibling gap; FieldLabel, FieldLegend, and FieldHint add no exterior margin.
Style helpers support custom controls inside the same group spacing contract without duplicating class contracts.
The family does not generate ids or accessibility relationships for the consumer.

tsx

<FieldGroup>
  <FieldLabel htmlFor="email">Email</FieldLabel>
  <TextInput id="email" type="email" aria-describedby="email-hint" />
  <FieldHint id="email-hint">We will never share it.</FieldHint>
</FieldGroup>

Public API

These props and helpers are compatibility contracts. Changes require migration guidance and release notes.

Prop	Type	Default	Contract
FieldGroup	HTMLAttributes<HTMLDivElement>	undefined	Groups a label, control, and hint with one 8px sibling gap.
FieldLabel	LabelHTMLAttributes<HTMLLabelElement>	undefined	Native label without exterior spacing.
FieldLegend	HTMLAttributes<HTMLSpanElement>	undefined	Visual legend text without exterior spacing; not a semantic fieldset legend.
FieldHint	HTMLAttributes<HTMLParagraphElement>	undefined	Supporting or validation text without exterior spacing.
TextInput	InputHTMLAttributes<HTMLInputElement>	undefined	Native text input.
TextArea	TextareaHTMLAttributes<HTMLTextAreaElement>	undefined	Native textarea.

Usage guidance

These rules keep the component recognizable across products without preventing deliberate composition.

Do

Use concise noun-phrase labels and useful format hints.
Show validation next to the field and explain resolution.

Do not

Do not use placeholder text as the only label.
Do not use FieldLegend as a substitute for semantic fieldset/legend.

Testing contract

The component should be verified as rendered UI, an interaction model, an accessibility surface, and a theme-aware visual artifact.

Unit

Each primitive forwards refs and native props.
Style helpers merge consumer overrides last and only FieldGroup supplies exterior sibling spacing.

Interaction

Label click focuses the associated control and typing updates the form model.

Accessibility

Label, description, validation, autocomplete, and disabled semantics are correct at responsive widths and 200% text zoom.

Visual

Measure label-to-input, label-to-textarea, and control-to-hint gaps; assert equal-height Field and Dropdown labels produce equal control tops; capture wrapped labels, no-hint, invalid, disabled, responsive, and both-theme states.

Related specifications

checkbox radio-group slider dropdown