React Input component

Preview

<Field>
  <Field.Label>Name</Field.Label>
  <Input placeholder="Ada Lovelace" />
</Field>

Usage

Use when

Single-line answers: name, email, password, phone, URL
Filtering a list or a ledger as the person types (type="search")
Short free-form values a list cannot cover

Avoid when

Multi-line text (use Textarea)
Numbers people step or scrub (use NumberField)
Selecting from predefined options (use Select or Combobox)
Boolean input (use Checkbox or Switch)
Date/time input (use DatePicker)

Implementation notes

Wrap in a Field for the label, description and error
Match type to the data: it drives validation and mobile keyboards
Placeholder shows format; it never replaces the label
Set invalid with a Field.Error that says why
A search field takes count while it filters; Escape clears, then leaves the field
shortcut is a hint only; register the key in the app

Installation

pnpm add @usefragments/ui

Import styles once from @usefragments/ui/styles. See the installation guide for framework and theme setup.

Examples

With description

Supporting text sits under the field and describes it.

<Field>
  <Field.Label>Password</Field.Label>
  <Input type="password" />
  <Field.Description>At least 8 characters.</Field.Description>
</Field>

Invalid

The danger edge with the reason under the field.

<Field invalid>
  <Field.Label>Email</Field.Label>
  <Input type="email" defaultValue="invalid-email" />
  <Field.Error match>Enter a valid email address.</Field.Error>
</Field>

Search

A filter with a clear button, Escape to clear and a live count.

<Input
  type="search"
  aria-label="Filter components"
  placeholder="Filter"
  count="3 of 71"
  shortcut="/"

Read only

A dashed edge: the value can be read and copied, not changed.

<Field>
  <Field.Label>Repository</Field.Label>
  <Input defaultValue="acme/web" readOnly />
</Field>

Sizes

Four heights on the control track: 24, 28, 32, 40.

<Stack gap="sm">
  <Input aria-label="Extra small" size="xs" />
  <Input aria-label="Small" size="sm" />
  <Input aria-label="Medium" size="md" />
  <Input aria-label="Large" size="lg" />
</Stack>

Adornments

A prefix and a suffix inside the field.

<Field>
  <Field.Label>Price</Field.Label>
  <Input startAdornment="$" endAdornment="USD" placeholder="0.00" />
</Field>

API reference

Component props
Prop	Type	Default	Description
`count`	`string \| undefined`	Not set	type="search" only: how many match ("3 of 40"), announced politely while there is a query
`defaultValue`	`string \| undefined`	Not set	Initial value for uncontrolled use
`endAdornment`	`React.ReactNode`	Not set	Content after the text: a glyph, a suffix or an action
`invalid`	`boolean \| undefined`	`false`	The danger edge and aria-invalid; say why in a Field.Error. Inside a Field, the Field's invalid does the same
`onValueChange`	`((value: string) => void) \| undefined`	Not set	Called with the new value on every change, the clear button and Escape included
`shortcut`	`string \| undefined`	Not set	A keyboard shortcut hint drawn at the end. Display only: the app owns the shortcut
`size`	`InputSize \| undefinedxssmmdlg`	`"md"`	Field height on the shared control track: 24, 28, 32 or 40
`startAdornment`	`React.ReactNode`	Not set	Content before the text: a glyph or a prefix
`type`	`InputType \| undefinednumbersearchtexttelurlemailpassword`	`text`	Native input type. search adds a leading glyph, a clear button, Escape to clear then leave, and the count slot
`value`	`string \| undefined`	Not set	Current input value (controlled)
`placeholder`	`string \| undefined`	Not set	Placeholder text shown when empty
`disabled`	`boolean \| undefined`	`false`	Dims the field and blocks input
`readOnly`	`boolean \| undefined`	`false`	Shows the value on a dashed edge without letting it change
`onChange`	`ChangeEventHandler<HTMLInputElement> \| undefined`	Not set	The native change event
`className`	`string \| undefined`	Not set	Class on the field box
`onKeyDown`	`KeyboardEventHandler<HTMLInputElement> \| undefined`	Not set	—

Accessibility

Field.Label names the input and Field.Description describes it
Field.Error is announced when it appears
The clear button is named Clear and keeps focus in the field
The search count is a polite status, silent while the query is empty

FieldparentField supplies the label, description and error
TextareaalternativeUse Textarea for multi-line text
NumberFieldalternativeUse NumberField for numbers people step or scrub
SelectalternativeUse Select when choosing from predefined options

Next steps

Accessibility guidanceThe keyboard, focus and naming rules every component carries.
Every componentThe catalog, grouped by what each component does.