On this page
Overview
Outline: a short value on one line, with a label and a description.
Show code, ProjectName.tsx
Ghost: a search atop a sidebar, only its icon and words until it is used.
Show code, SearchInSidebar.tsx
Variants
- Outline
In forms, dialogs, panes and toolbars, and a field on its own on a page. The default.
- Ghost
A search in an application's chrome: atop a sidebar, among quiet buttons in a toolbar, or in a palette.
Show code, Variants.tsx
Outline
An outline field has no fill of its own. It takes the background of what it sits on, such as a card or a dialog. Its label rests inside it and floats into the edge, which opens behind it.
- It is as tall as a button of its size, so the two line up in a row.
- Stacked in a Column or a Grid, it keeps a little room above it for its floated label.
- A field on its own on a page, or in a long form, takes the large size.
- It can be given a fill of its own where it needs one.
Ghost
A ghost field has no edge. A faint fill at rest shows where to type, and deepens under the pointer. Focus draws the accent edge an outline field takes.
- It has the outline field's corners, so the two sit together in a row.
- Keep it to toolbars, an application's chrome and palettes. In a form, a faint fill says less than an edge, so a form's fields are outline.
- Its label floats inside the fill, above the value, as there is no edge to cut a notch in, and stays within the field's height, so a ghost field is as tall as an outline one.
- A read-only or disabled ghost field keeps a fainter fill, quieter than one to fill in.
- An invalid ghost field shows a red edge.
- The CommandPalette's search is a large ghost field that keeps its fill.
Show code, SearchInToolbar.tsx
Sizes
Outline and ghost fields come in the three control heights of the scale: small, medium and large.
- A field lines up with a button of its size.
- Small is for a field with its label hidden, as in a dense toolbar or a filter row. A small field that shows its label takes the medium height, so the label and the value each keep room, and says so in the console while developing.
Show code, FieldsBesideButtons.tsx
Prefix and suffix
Short text in line with the value, which forms don't submit. Pressing it places the caret.
Show code, PrefixAndSuffix.tsx
Icon and end action
An icon at the start only decorates the field.
- The end can hold a control, such as a button that shows the password.
- That control takes a quiet look to sit inside the field.
Show code, IconAndEndAction.tsx
Anatomy
Field
Control
Label
Start icon
Prefix
Input
End action
Description
Show code, TextFieldAnatomy.tsx
Behaviour
States
The label rests in an empty field and floats into the outline on focus or with a value.
- Under the pointer, the outline darkens.
- Focus alone draws it in the accent, twice as thick.
Show an error
An error marks the field invalid and shows under its description. Say how to correct the value.
- Check on leaving the field and on submit, never while people type.
- Clear the error as soon as the value fits.
Show code, Validation.tsx
Search
A SearchField's clear button and Esc empty the query.
- Its label is for assistive technology, unless it is set to show; with the label hidden, its placeholder says Search unless it is given another.
Textarea sizing
A Textarea keeps its height and scrolls, or grows with its text instead.
- People resize it by its bottom edge, by dragging or with the arrow keys.
- The grip, two short diagonal lines in the end corner, shows under the pointer and while the field has focus. A Textarea that grows with its text has none.
Show code, TextareaSizing.tsx
Adapting to width
A field fills its container; set the width there.
- A long prefix is cut short so the value keeps its room.
Show code, LongAddress.tsx
Rules
Fields show where to type, name their value, and say what they take.
Use it when
- A short value on one line, such as a name or an e-mail address
- A value with a fixed start or a unit, such as a size in GB
- Searching a list, a table or a sidebarSearchField
- Text over several lines, such as notesTextarea
Show code, OutlineForm.tsx
Show code, GhostForm.tsx
Kinds of value
Say what kind of value each field takes, such as an e-mail address, so the browser can fill it in and show the right keyboard.
Read-only values
Show a value people can't change as read-only, so they can still focus and copy it.
- Its outline stays as at rest and doesn't answer the pointer. The value stays as dark as any other.
- A disabled field can't be focused, copied or submitted.
Labels
Name the value in a short noun phrase, and keep lasting instructions in the description.
Show code, LabelAndDescription.tsx
Show code, PlaceholderAsLabel.tsx
Accessibility
| Key | Action |
|---|---|
| Tab, Shift+Tab | Moves to the next or previous field, then its end action. |
| Esc in a SearchField | Clears the query; in an empty one, the key goes on. |
| ↑, ↓ on a resize edge | Shrinks or grows the Textarea by a line. |
| Shift+↑, Shift+↓ on it | Shrinks or grows it by five lines. |
| Home on a resize edge | Restores the Textarea's minimum height. |