Field

When to use

• Short, free-form, single-line text: a name, an email, a URL, a search term, a coupon code. If the answer is not a fixed set of options, a field is the right control.
• A visible label on every field. Pass label; when the design hides it, use visuallyHiddenLabel so the name survives. Placeholder text is a hint, never the label.
• Guidance before and failure after: supportingText explains the format up front, errorMessage (or validate) replaces it when the value is wrong. Keep both to one short sentence.
• Format and unit cues that belong to the value: prefixText and suffixText for https:// or USD, and the prefix and suffix slots when the cue is itself a control such as a country code or a Search button.
• Hard limits stated up front: set maxLength with showCharacterCounter so nobody discovers the limit by being truncated.
• A mobile keyboard that matches the data: forward type, inputMode, enterKeyHint and autoComplete so people type less.

When not to use

• For answers that span several lines. Use Textarea.
• For a number people step or adjust. Use NumberField, which owns increment, decrement and number formatting.
• For choosing from a known list. Use Select for a short list, or Combobox when people need to filter a long one.
• For a search box with results or suggestions. Use Search, or SearchSuggest when suggestions appear as you type.
• For a yes/no or one-of-few choice. Use Checkbox, Radio or Switch.
• For a group of related fields. Wrap them in a Fieldset so the group has one name and one error; do not repeat a label across fields.

Installation

pnpm add @tessinaui/ui

Usage

import { Field, FieldDropdown, FieldDropdownItem, FieldSkeleton } from "@tessinaui/ui";

<Field label="Email" placeholder="you@example.com" supportingText="We never share it" />

Usage rules

• Always pass label. A field without a visible label needs visuallyHiddenLabel so the name survives for assistive tech — placeholder text is never a label.
• supportingText is for guidance; errorMessage is for failure. When both are set the error replaces the supporting text (no layout shift next to an open keyboard).
• Don't set intent="error" by hand to signal a validation failure — pass errorMessage (or validate) and let the field derive the error state, aria-invalid and the announcement.
• Prefer prefixText/suffixText for static in-field text (https://, USD) and the prefix/suffix slots for real controls (FieldDropdown, Button).
• Sizes below lg render 16px input text on phones so iOS Safari never zooms the page on focus; don't override the input font below 16px on mobile.

Examples

Default

Variants

Three shells: the default outline box, a filled well, and an underline bottom rule for dense forms. Filled is a tinted well with no outline at rest or on hover: the focus ring is its outline, and an error or other intent draws the border back. It matches the filled Textarea, and it reads best on a filled Form, where the panel sets the well apart. Prefer outline where a field sits straight on the page — the outline is what marks it as a place to type. Underline is square whatever rounded says, trades the focus ring for an inset 2px bottom band in the intent colour, and never gains a fill — disabled and read-only dim the rule instead. A floated inside label sits above the rule with no notch to cut. prefix / suffix slots keep their own boxes; pass variant to a FieldDropdown to match.

Intents

Five visual intents — none, error, warning, success, info — recoloring border, focus ring and supporting text. Intent is presentation; validation state comes from errorMessage/validate.

Validation

errorMessage for consumer-owned errors, validate (+ validationMode) for field-owned checks. Both render the same announced error row, join aria-describedby and set aria-invalid.

Sizes

Icons & Clearable

Decorative icons render as plain glyphs (no button semantics); pass …IconOnClick + …IconLabel to make one an actual named button. The clear button appears only while the field has a value, sits in the tab order as "Clear ‹label›", and Esc clears from the input.

In-field affixes

Static text inside the container: prefixText / suffixText, plus monospace for codes and IDs. Affix text is exposed to screen readers through the input's description.

Prefix & Suffix slots

<FieldDropdown> before the container and a <Button> after it, sharing the field's size and rounded. The character counter stays pinned to the input's trailing edge, never under the suffix button.

On-color

On a coloured plate, tone resolves from the surrounding Surface automatically (explicit prop wins, like Button): the well, text, icons, clear button and FieldDropdown derive from the surface ink contract; intent text uses the on-ink palette.

On an error, info or success plate a field has one text tier: supporting text, the counter, the "(optional)" marker, affixes, the placeholder and a resting inside label all render at full ink, because a dimmed copy of that ink cannot reach 4.5:1 against the well (see Surface › Muted inks on intent plates). Put the hint in the label or supporting text there, not in the placeholder. A placeholder still renders, at full ink, but it reads like a value.

States

optional, isLoading (spinner swaps a decorative trailing icon in place; an interactive trailing icon stays mounted and disabled, with the spinner on its input side; the clear button stays available; edits blocked, aria-busy), readOnly (value selectable, state paint suppressed), and FieldSkeleton.

Disabled

RTL

dir="rtl" aligns the label, helper and error rows right, moves the leading icon and prefixText to the right edge, and moves the clear button, trailing icon and suffixText to the left. An inside label floats from the right. Leave dir unset and the field follows the page's direction.

API Reference

Field

All other native <input> attributes (type, name, autoComplete, inputMode, enterKeyHint, …) are forwarded to the input. The root forwards wrapperClassName; the input carries className and the rest — the documented form-control exception shape.

FieldDropdown

FieldSkeleton

Controlled Usage

const [value, setValue] = useState("");

<Field
  label="Search"
  value={value}
  onChange={(e) => setValue(e.target.value)}
  clearable
  onClear={() => setValue("")}
  showCharacterCounter
  maxLength={100}
/>

Clearing (button or Esc) fires a real onChange with the empty value, so form libraries stay in sync — in uncontrolled mode the DOM input is cleared too.

Migrating from labelPosition

The old prop still works for one minor and warns in development. Values are logical: start follows the reading direction instead of lying in RTL.

Do / Don't

• Do pair every field with a visible label; don't rely on placeholder text.
• Do use errorMessage/validate for failures; don't hand-set intent="error" as the only error signal.
• Do match size and rounded across Field and FieldDropdown, and leave size off a suffix Button — Field seats it at its own height. The button family's ladder is 32/40/48/56/96 against the field family's 32/36/40/48/56, so a Button placed beside a field outside the slot takes fieldSuffixButtonProps(size), never the Field's own size. Don't mix radii inside one composition.
• Do use readOnly for values the user may copy; don't use disabled for that — disabled leaves the focus order and drops contrast.
• Do keep maxLength + counter for hard limits; don't surprise users with silent truncation.

Keyboard input hints

Forwarded native attributes drive the right mobile keyboard: type="email", inputMode="decimal", enterKeyHint="search", and autoComplete (WCAG 1.3.5 — set it on personal-data fields: email, name, tel, postal-code, …).

Accessibility

Pattern: native labeled text input (no APG composite widget — the input, its label and its descriptions are the contract). Plumbing is Base UI Field: generated ids pair label↔input, and description, error, info text, affixes and the counter limit all join the input's aria-describedby.

• The error row lives in a pre-mounted polite live region, so inline errors are announced without moving focus; aria-invalid is set only while actually invalid — never on a pristine required field.
• required is the native attribute (announced by AT); the * is aria-hidden so the name stays clean.
• The clear button is named "Clear ‹label›" and is keyboard-reachable; decorative icons carry no role at all.
• isLoading sets aria-busy on the input; the spinner itself is decorative (one announcement per state, owned by the control).
• Character counter: the limit is a static description ("Up to N characters"); remaining count is announced politely at ~90% and at the limit, never per keystroke.
• Touch: container and interactive icons keep a ≥44px floor on phones; input text is ≥16px on phones so iOS never auto-zooms.
• Forced colors / high contrast ride the token system; the focus ring is the hard-gated --focus-ring pair.
• Contrast (audit-gated, both themes): supporting text none 4.74/7.66 · error 4.77/5.20 · warning 7.14/13.68 (tinted foreground — raw amber fails) · success 4.95/11.13 · info 5.20/7.51 · floated label focus 17.93/15.72. The resting outline is soft on purpose (1.48:1 light, 1.91:1 dark): the label marks the field. Hover draws it in the text colour (19.80/18.97), focus hands over to the ring, and every intent draws its own border.
• AT matrix: VoiceOver + Safari passed 2026-09-14 — an invalid field reads "Username, Spaces are not allowed, invalid data, edit text"; a helper reads "Email, We only use it for receipts, edit text". NVDA and JAWS are untested (§5.6).