Component docs

Input

A single-line text field with a visible label, optional description, and an error message that is announced to assistive technology.

Basic usage

Install the package:

pnpm add @design-schema/react @design-schema/tokens

Import the stylesheet once for the app, then the component:

import '@design-schema/tokens/calm-precise/css';
import '@design-schema/react/index.css';
import { Input } from '@design-schema/react';

Examples

Email address

import { Input } from '@design-schema/react';

<Input label="Email address" name="email" />

Props

14 rows

Prop	Type	Default	Description	Platforms
label required	string	—	Visible label (visually hidden with `hideLabel`). Never replaced by a placeholder. Accessibility: Programmatically associated with the field (label/for on web, accessibilityLabel on native).	web, lit, rn, swiftui
name required	string	—	Field name used by the enclosing Form when collecting values.	web, lit, rn, swiftui
value	string	—	Controlled value. Omit for an uncontrolled field.	web, lit, rn, swiftui
defaultValue	string	—	Initial value for an uncontrolled field.	web, lit, rn, swiftui
placeholder	string	—	Example input shown while empty. Never the only description of what to enter. Accessibility: Placeholder text is muted and disappears on input; it is not a substitute for label or description.	web, lit, rn, swiftui
description	string	—	Persistent helper text below the label explaining format or purpose. Accessibility: Linked to the field with aria-describedby / accessibilityHint.	web, lit, rn, swiftui
type	text \| email \| password \| number \| search \| tel \| url	text	Input type. Drives the keyboard on touch platforms and browser validation on web.	web, lit, rn, swiftui
required	boolean	false	The field must have a value to submit. Shown in the label, not only by color.	web, lit, rn, swiftui
hideLabel	boolean	false	Visually hide the label (it remains the accessible name). Only for a field whose context already names it: a DataGrid cell editor, a Search.	web, lit, rn, swiftui
size	sm \| md	md	sm for fields inside grid cells and toolbars: minimum target height, tighter padding, small type.	web, lit, rn, swiftui
disabled	boolean	false	Not editable and not submitted. Stays visible and readable.	web, lit, rn, swiftui
invalid	boolean	false	Marks the field as failing validation. Usually set by the Form; can be set directly.	web, lit, rn, swiftui
error	string	—	The error message. Setting it implies `invalid`. Explain what is wrong and how to fix it. An empty string counts as unset, so it implies nothing and never leaves an empty alert. Accessibility: Rendered in the error slot with aria-describedby and role=alert so it is announced when it appears.	web, lit, rn, swiftui
autocomplete	string	—	HTML autocomplete token (e.g. `email`, `given-name`). Enables WCAG 1.3.5 input-purpose identification.	web, lit

Events

3 rows

Event	Type	Description	Platforms
onChange	onChange / change / onChangeText	Fired on every value change with the new string value, and nothing else (web handlers do not receive the ChangeEvent).	web, lit, rn, swiftui
onFocus	onFocus / focus (native, retargeted — no CustomEvent)	Fired when the field receives focus. No payload: web and rn handlers are called with no arguments, not the FocusEvent (a forwarded Tooltip handler gets none either).	web, lit, rn, swiftui
onBlur	onBlur / blur (native, retargeted — no CustomEvent)	Fired when the field loses focus. The usual moment to validate. No payload: web and rn handlers are called with no arguments, not the FocusEvent.	web, lit, rn, swiftui

Accessibility

Decisions this component leaves to you

Supply the label. It is associated with the control for you, but the words are yours — a placeholder is not a label.

Supply the error text when the value is invalid. The component links and announces it; it cannot write it.

Required props that carry accessibility meaning: label. Each is described in the props table above.

Implicit ARIA role: textbox.

Anatomy

labeldescriptionfielderrorMessage

What generation guarantees

Label association — The label is programmatically associated with the control, not merely placed beside it.

Error identification — An invalid value is identified in text and linked to the control — never signalled by colour alone.

Visible focus — Keyboard focus is always drawn, from the theme’s focus tokens, and is never removed.

Keyboard operable — Everything the pointer can do here, the keyboard can do — see the keyboard section.

Target size — Interactive targets are at least 44×44 CSS pixels — the touch-first size, not the minimum.

Contrast — Text and meaningful non-text contrast meets WCAG AA; the pairs are listed below.

Contrast pairs

4 rows

Foreground	Background	Level
color.foreground	color.background	AA
color.foreground.muted	color.background	AA
color.foreground.danger	color.background	AA
color.border.strong	color.background	AA (non-text)

This component does not animate, so it has no reduced-motion behaviour to describe.