# Text field

> Text that people type, of one line or several, kept as typed and checked when committed.

A text field takes text that people type: a name, a title, a note. It holds one
line, or several where the text is naturally longer.

## When to use

Use a text field for text with no fixed set of answers. When the answer is one
of a known few, offer a [select](https://ui.publictheta.com/components/select.md); when it is a number or a
date, use the field made for it, which understands what is typed.

## Best practices

**Keep text as it was typed.** Do not trim, change case or otherwise rewrite
what people enter, unless the field's purpose is a form they expect. Where space
at the ends is never meant — an address, an identifier — drop it when the text
is committed, and treat space alone as no text.

**Never cut typing short.** A limit on length is checked when the text is
committed and reported then. A field that refuses characters past its limit
breaks an input method's composition, and loses what was pasted without saying
so.

**Count characters as people see them.** A limit of twenty characters allows
twenty of any script, and an emoji is one.

**Say what form is expected before it is wrong.** Where text must follow a
pattern, say so in the label or beside the field, not only in the error.

**Choose one line or several by the text.** A single line for a name or a title;
several for a description. In a field of several lines, Return makes a new line,
and Command-Return (Control-Enter) commits.

**Label the field with what it holds.** A placeholder is not a label: it
disappears when typing starts.

## Platform considerations

**Keyboard.** Editing follows [Editing values](https://ui.publictheta.com/foundations/use-field.md).

**Touch.** The field is at least 44 CSS pixels tall, with text large enough that
the page is not zoomed on focus. The keyboard's Return key says what it does:
a new line in several lines, done in one. A field of several lines grows with
its text.

**Assistive technology.** The field is a text field with its name; text that
breaks a limit marks it invalid.

## Behaviour

Each statement is verified by a test in Chromium, Chromium (touch), Firefox, WebKit, WebKit (touch), unless it names the environments it applies to or is marked open.

### Semantics

- Is a text field with its name, of one line or several.
- Has no accessibility violations, valid or invalid.

### Typing and committing

- Text is kept exactly as typed, spaces included.
- Where space at the ends is never meant, it is dropped at commit, and space alone is no text.
- A pattern that is not a regular expression constrains nothing, rather than failing.
- A limit on length never stops typing; it is reported at commit.
- Length is counted in characters as people see them.
- Text that does not match the field's pattern is invalid.
- A composition longer than the limit is not cut short. *(Chromium, Chromium (touch))*

### Several lines

- The key that ends a line is offered as a new line in several lines, and as done in one.
- Enter makes a new line and does not commit.
- The command key with Enter commits, and so does leaving the field.
- Escape abandons the edit.

### Touch

- On a touchscreen, the field is at least 44 pixels tall. *(Chromium (touch), WebKit (touch))*

## Reference implementation

React: `npx shadcn@latest add https://ui.publictheta.com/r/text-field.json`