Field

Preview

Installation

npx echo-ui-cli add field

At a glance

Version

0.3.0

Weight

887 B · 38.7 KB with what it imports · 1.4 KB of CSS (minified and gzipped; React not counted)

Needs

@base-ui/react, size (Echo, brought with it)

Keyboard

• start is decoration, hidden from assistive tech: whatever it says ("search", a currency) belongs in the label too. A control in end is its own button with its own name.
• A native <input>; type passes through, so email, password and search keep their keyboard and autofill behaviour.

Reduced motion

The well doesn't press in or take strikes, and the caret is the browser's own. Only the focus edge's colour fades in.

Usage

import { Field } from "@/echo/field";

<Field label="Name" placeholder="Ada Lovelace" />

Composition

Field

Examples

<Field
  aria-label="Search"
  start={<SearchIcon />}
  end={<HardwareButton size="sm" iconOnly aria-label="Clear search" icon={<ClearIcon />} />}
/>

<Field label="Timeout (ms)" defaultValue="250" end="ms" mono />

<Field label="Name" placeholder="Ada Lovelace" />

<Field label="Session code" placeholder="000-000" mono />

<Field label="Query" value={q} onValueChange={setQ} />

<Field
  label="Email"
  type="email"
  autoComplete="email"
  description="We only use it to send the session link."
  error={valid ? undefined : "Enter an email address, like ada@example.com."}
  value={email}
  onValueChange={setEmail}
/>

Accessibility

• start is decoration, hidden from assistive tech: whatever it says ("search", a currency) belongs in the label too. A control in end is its own button with its own name.
• label renders a real <label> tied to the input. With no visible label, pass aria-label or aria-labelledby.
• A native <input>; type passes through, so email, password and search keep their keyboard and autofill behaviour.
• A placeholder is not a label — it disappears as soon as someone types.
• description and error are linked with aria-describedby, and error sets aria-invalid, through Base UI's Field. The error is words plus a square pip, never colour alone.
• Set autoComplete on a field that asks for the user's own information (email, name, current-password), so autofill works and the purpose is machine-readable (WCAG 1.3.5).

Motion & sound

Motion tokens

--echo-duration-swap

Reduced motion

The well doesn't press in or take strikes, and the caret is the browser's own. Only the focus edge's colour fades in.

Props

Anti-patterns

• Don't show an error as a red border or colour alone. Pass error with words that say what to fix; that's what gets read out.
• The lit focus edge is the one accent; do not tint the well or the text with it.

Changelog

• v0.3.0 · 2026-10-12 · AddedThe drawn device (echo-ui-core, echo-ui-cli, every component that draws its own material). A seed's new render setting is molded (Echo as it has always been: plastic lit by one key light) or drawn: the same parts drawn in the ink, the way a spec sheet draws a key. Every part is outlined at one weight (--echo-line, --echo-line-width), hollow on the body; a raised part stands on a hard ink edge as deep as it rises and travels down it when pressed; a recess is an outline drawn inside; something floating stands on a deeper edge. There's no light, so no gloss, no soft shadow and no glow: what a molded device lights (an LED, the rail, a readout, the focus ring, a fader's knob, a radio's pip) is solid ink, and a low-emphasis action is its label underlined. In black and white (the accent the ink) "on" is solid ink and what's drawn on it inverts: a switch's thumb turns paper, a fader's knob is knocked out with a paper ring. The primary key is the paper key that stands highest, on an ink edge twice as deep as a neutral one's, the way a spec sheet draws its CTA. The accent stays the seed's own colour as a flat fill for what's on (a chosen segment, a checked box, a slider's travel, a switch that's on), so an acid highlighter is acid, not the olive a molded device holds it to; what's drawn on it is the ink, or the body when the accent is too deep for the ink. Pressing, travel, sound, what each material is for and every contrast guarantee are unchanged. npx echo-ui-cli style set render drawn turns it on; a style sets it in its seed; the published style and config schemas describe it, and DESIGN.md says how a drawn device builds. A molded device renders exactly as before: every line is 0px wide there, and each drawn value a component reads (--echo-drawn-fill, -on-fill, -ink, -rule, -glass, -hollow, -decoration) is initial, so it falls back to what the component always drew. HardwareButton's bed is the one new hand-tuned shadow: a drawn key stands on its own edge instead of being drawn in a recess.
• v0.3.0 · 2026-10-12 · ChangedEvery item needs echo-ui-core 0.3.0 (all components). The drawn device, readability past AA and the design tests live in core, and the components that use them are built against it, so each item now declares echo-ui-core >=0.3.0 <0.4.0. Update core with the items: npm install echo-ui-core@^0.3.0 (or your package manager's), then npx echo-ui-cli update. An item whose files didn't change is the same code under a new version; the 0.2.0 files stay published.
• v0.2.0 · 2026-10-04 · AddedThe light device (echo-ui-core, echo-ui-cli). Echo can be light: a pale chassis makes a device molded in light plastic, like a white calculator or a cream radio, and a dark one makes the device Echo has always been. There's no setting and no mode to switch; the chassis decides (devicePolarity, and values.polarity on the theme). On a light device the page is light: its ground, the well, is the body barely set in. Caps get their own ladder, a step lighter than the body with a lit rim that stops short of white, so they keep their bevel; undersides and seams are shaded darker; dim text moves toward the ground by the same step as on a dark device, and reads about 6:1 on it. Screens are paper glass printed in ink, because a glow on a pale body is a smudge. What's lit (an LED, the current rail) is still the accent, held to 3:1 on every ground, so on is brighter than off; the text it prints (a readout, a count, a current tab) and the focus ring are the accent's ink, a step deeper and held to AA, in the new accent-ink role. The primary cap is the same cap as a dark device's, the accent with a light label: its label is the new primary-cap-ink role, and progress cells, loader dots and a meter's fill, the same plastic, read 3:1 on the page. A neutral cap or a slider that fills with it under its own dark label fills with the new pour-* roles, the accent's pale stops. Shadows are drawn at half their weight, in a deep colour of the body's own hue (--echo-cast-ink) instead of black. Every guarantee holds as it does on a dark device, and the contrast sweep now runs on light bodies too. A dark seed makes exactly the theme it did before, and the new roles equal the ones they stand for there. The components that mixed a recess toward black, painted paper in the text colour or lit a pillow of light with it read the theme's new --echo-shade-ink, --echo-paper-stock and --echo-paper-ink instead, with the old value as the fallback, and a reflective screen reads --echo-screen-*; the components that print a lit label read --echo-primary-cap-ink and --echo-accent-ink the same way; every rail is drawn in the glow, and every focus ring, the ring recipes included, in the ink. style use wears a light style now, and style check says which device a style makes. A dark screen tint on a light body is still refused: one text colour can't serve both, and the theme says so.
• v0.2.0 · 2026-10-04 · AddedThe rest of the inputs: Toggle, Toolbar, Meter, RangeSlider, and two instruments, Knob and LevelMeter. Plus start and end on Field. - Toggle / ToggleGroup: the quiet toolbar key. On is the cap held down in its well, not a light; a group shares one well, with arrow keys between its keys, multiple or at most one. - Toolbar / ButtonGroup: caps sharing one long well. A Toolbar is one tab stop with the arrow keys, Home and End along it, and sm controls; Toggles and ToggleGroups inside join its order by themselves. A ButtonGroup is the look alone. - Field start / end: a search icon or a currency sign engraved into the well before the text; a unit or a small key (clear, show password) after it. - Meter: a measurement in a range (storage, battery), a tube of lit plastic that settles to its level with a small slosh; marks engrave a limit without a second colour. - RangeSlider: two of Slider's knobs on one rail for a span, named "…, minimum" and "…, maximum"; they never cross. - Knob: a rotary cap with a lit scale. Drag it, wheel it once focused, or use the slider keys; it clicks at each step and settles onto each detent on a spring. - LevelMeter: a live level as LED cells with real ballistics and a held peak. It draws without re-rendering, stops once it's still, and tells a screen reader its level at most once a second.
• v0.2.0 · 2026-10-04 · AddedOne size on everything with a height. Field, Select, NumberField, OtpField and Segmented take size="sm" | "md" | "lg" (32, 44 or 60px), matching HardwareButton, and all of them read a SizeProvider around them. md is exactly what they were. Avatar gains xs (inline with a line of text) and xl (a profile header).
• v0.2.0 · 2026-10-04 · AddedA new error shakes the field; a Select unrolls from its cap. When a Field's error appears or changes, the field is shoved sideways and swings back through to rest on a spring, the way a latch that won't take the key bounces back. A Select's list now grows out of the edge of the trigger it drops from, rather than scaling up from its own middle. Neither moves under reduced motion.
• v0.2.0 · 2026-10-04 · AddedHelp text and errors on Field and Textarea: description and error props, linked to the control with aria-describedby, with aria-invalid while there's an error. The error is words and a square pip, not a colour. Both now build on Base UI's Field, so re-adding them also installs @base-ui/react.
• v0.2.0 · 2026-10-04 · ChangedComponents whose shadow is a recipe read it by name. 71 shadows in 54 items now say var(--echo-shadow-<name>, <the same shadow>), so they look exactly as they did (every docs page was compared before and after) and follow a theme's recipes. Scope declares the recipes that read the accent again, so a Scope's own colour still reaches its focus rings and glows, and reflective screens do the same for theirs. Shadows that move with their part (a cap's drop as it's pressed) stay in the component.
• v0.2.0 · 2026-10-04 · ChangedField is the same height as Select and NumberField. Its input kept the browser's own 1px padding above and below on top of its 44px, so a Field stood 46px tall beside a 44px Select and the two never lined up in a row. It is now exactly 44px; everything below a Field moves up 2px.
• v0.2.0 · 2026-10-04 · ChangedComments only, no behaviour change. Comments in the component source used to cite documents, milestones and ticket numbers from Echo's own planning, none of which exist in your project. The citations are gone and the sentences around them stay. Where a comment was only a citation, it now says what it meant. Three development warnings (HardwareButton's engraved/caption checks and StatusDot's missing-label check) also dropped the ticket code at the end of the message. echo-ui diff will show changes in most items; none of them are to code.
• v0.2.0 · 2026-10-04 · ChangedAn item's version is now a function of declared data, not of how the changelog is formatted. The version an item ships under is published once and never rewritten, and it used to be inferred from prose: a regex for a bolded "Breaking" run across the whole unreleased section, and attribution by "does a bullet mention this name in backticks". One breaking entry therefore moved every item that changed that cycle, and an entry explaining that "Menu and Sheet are unchanged here" filed itself as a change to Menu and Sheet — which it really had.
• v0.2.0 · 2026-10-04 · ChangedBreaking: every control takes a ref, an onBlur and an onFocus — and the two that were wide open are now closed. Four of 49 components could receive a ref, and onBlur appeared in zero public prop types, so react-hook-form's uncontrolled register() — which needs exactly ref, onBlur and name — could not work with any Echo control.
• v0.2.0 · 2026-10-04 · ChangedThe agent brief says Echo has not shipped. llms.txt and the MCP server's instructions led with npx echo-ui-cli init, and that name on npm is a reserved stub with no executable — so a model following the brief wrote an install step that fails with npx's own error. The brief now opens with the caveat, and the docs carry it on every surface that shows a command. One switch (CLI_RELEASED) silences all of them at launch, and a test refuses to let one move without the others. Affects all components only in what the brief says about installing them; no item's props, CSS or rendered semantics change.
• v0.2.0 · 2026-10-04 · ChangedEcho's home is echo-ui.com. The registry, the docs and the packages all move to it from echo.nawwara.studio. Nothing was published under the old host, so no echo.json anywhere points at it and there is nothing to migrate — this is the last release where that is true.
• v0.2.0 · 2026-10-04 · ChangedControls must have an accessible name, or they don't compile. Switch, Checkbox, Slider, Segmented, Select, RadioGroup and Progress need aria-label or aria-labelledby; Field and Textarea need label, aria-label or aria-labelledby; an iconOnly HardwareButton needs aria-label or aria-labelledby. Breaking for code that left them out: add the name. A control inside a <label> points aria-labelledby at the label's text.
• v0.2.0 · 2026-10-04 · ChangedDescriptions that described an older look. Tabs (a lit rail, not a lit cap), Select (CSS fades, not a GSAP exit), and Badge, Segmented, Select and Field, which named the default seed's raspberry instead of the accent.
• v0.2.0 · 2026-10-04 · ChangedWeights, line heights, letter-spacing, z-index, border widths and icon sizes come from the theme scales in all components, with the old value as a fallback, so components keep working with echo-ui-core@0.0.1. Strays moved to the nearest step: most by under a pixel; HardwareButton icons are 14/16/20px (were 15/17/19).
• v0.2.0 · 2026-10-04 · FixedA light device's recesses keep the body's hue in Chromium (echo-ui-core, BUG-166). Chromium drops the hue of a colour under 0.02 chroma when it mixes in oklch, and draws the mix at hue 0, a rose. A light device's plastic is that grey, so on a lilac body every field, track and rail was pink. A mix made only of greys is made in oklab now, which has no hue to lose; a mix with an accent in it stays in oklch. On a dark device nothing you can see changes.
• v0.2.0 · 2026-10-04 · FixedSign-in fields had no autocomplete (WCAG 1.3.5). Field takes an autoComplete prop (email, current-password, one-time-code), so autofill and password managers fill a sign-in.
• v0.2.0 · 2026-10-04 · FixedContent now reflows into a 320px screen (400% zoom) and survives a doubled browser text size (WCAG 1.4.10, 1.4.4), across all components. Select's 180px floor, NumberField's readout, Segmented and Steps as flex items, EmptyState's grid columns, and Avatar's fixed-pixel disc all gave way; Panel counts its padding inside a width you set (box-sizing: border-box), so a <Panel style={{ width: 220 }}> is now 220px wide overall rather than 260px.
• v0.1.0 · 2026-09-11 · Known limitationsNo OTP field. A one-time code is a mono Field. A six-digit code wants per-digit boxes and paste-splitting.