Patterns
Choosing a component
Which component to use when people pick something, when you tell them something, for what floats above the page, while they wait, and for a row.
Several components can look right for the same job. These tables pick one per situation. Each component's own doc says how to use it once chosen.
When it applies
Whenever you put a control, a message, a popup or a row on a screen. Products don't override these choices; a product-specific case goes on the product's page.
Rules
Picking something
| You need | Use |
|---|---|
| To act on one thing | A menu (DropdownMenu); press and hold on a phone opens the same menu (ContextMenu) |
| Yes or no, applied at once | Switch |
| Yes or no, applied on Save | Checkbox |
| One of 2 to 5 answers, submitted with a form | RadioGroup |
| Another view of the same content | SegmentedControl |
| Sections of one page, each with its own content | Tabs |
| One of up to 10 values | Select |
| One of many values | A select with a search row at the top of its list (ComboboxSelect) |
| A few of several values | A multi-select: a box before each item, and the field shows the chosen values (ComboboxSelect with multiple) |
| A few of many values (people, agents, labels) | A multi-select with search: chosen values become chips in the field, and typing continues after them (ComboboxSelect with multiple, or Combobox with its chips) |
| To filter a list | A filter: a select or combobox opened from a PickerTriggerButton |
| To change one property of an item in place | The value in a DescriptionList opens a picker |
Telling people something
| Situation | Use | Stays |
|---|---|---|
| Something the person just did has a result | Toast | A few seconds |
| They need to know it before acting | Banner, inside a dialog or form | Always |
| Something in one panel failed: an agent won't start, a setting didn't save | A full-width banner under the panel header (PanelNotice, Panel) | Until it is fixed |
| The state of the whole workspace: a computer offline, a quota nearly full, an update | The notification center (NotificationCenter), with an attention dot on the bell | Until it changes |
| Something happened elsewhere that the person should see | Activity (ActivityInbox); its entry point shows an attention dot or a count | Until it is read |
| An agent needs approval | An action card in the conversation (MessageActionCard), also listed in Activity | Until it is handled |
| The person must decide now | Dialog | Until they decide |
| An input is invalid | The input's error state (Field) | Until it is fixed |
| What an icon means | Tooltip | While hovered |
- Never put anything in a toast that would confuse people if they missed it.
Overlays
| Situation | Use |
|---|---|
| One sentence on hover | Tooltip |
| A person or agent, on hover | A profile card (PreviewCard) |
| A list of actions, on click or press and hold | DropdownMenu |
| One value, on click | Select, with search when there are many values |
| Several values, on click | A multi-select, with search when there are many values. Choosing a value doesn't close the list |
| A little input, on click | Popover |
| Details and settings people look at for a while | Drawer |
| A large form filled in one pass | The wide Dialog; see Forms |
| A place to go, on a phone (switch workspace, Working now) | A bottom sheet (Drawer). Picking a value is still a select list; acting on something is still a menu |
| A short explanation, on a phone | A bottom sheet (Drawer) |
| A confirmation | AlertDialog |
| Task details | A centered dialog, at most 760px wide, full screen on a phone (Tasks) |
- Put a scrim behind every centered overlay: dialogs, confirmations, search, task details, large forms. How overlays move is in Motion.
Waiting
| Situation | Use |
|---|---|
| The layout is known | Skeleton |
| The duration is unknown, and there is no layout to hold | The pixel spinner (Spinner) |
| The percentage is known | Progress |
| A button started the wait | The button's loading state (Button) |
- Don't use pink for any of these. They are passive.
Rows
| Where | Use |
|---|---|
| A phone list: channels, direct messages, settings, members | ListRow |
| Agents and people on a detail or profile page | ListRow, in an inset group |
| The desktop sidebar | The sidebar row (Sidebar) |
| Activity and notifications | InboxItem |
| A message found by search | The search result row (Search) |
| A task | TaskCard, on a board or in a list |
Related
- Composites: things built from these components.
- Feedback: errors by scope.
- Forms: which controls apply at once and which are saved.