Input

Which component to use for an action someone presses or a value someone enters or picks. Find the job, take the component, and read the “not when” before you commit: it names the thing people reach for by mistake, and what to use instead.

At a glance

Job	Use	Not when	Instead	Because
Let someone do an action, named with a verb	`Button`	The thing reports a state rather than doing something	`Tag`	A status is a tag and an action is a button; beside each other they must differ in shape, not only colour.
		There are several actions on one object and not room for them all	`Menu`	A menu holds the secondary actions behind one trigger with the full menu keyboard contract.
		A row of buttons picks one view of the same thing	`Segmented`	A choice between views is a radiogroup; buttons are acts, and a pressed button does not say which one is chosen.
		A whole card is the link	`Card`	`CardLink` makes the card one link target instead of a card with a button inside it.
Set a few related actions as one adjoining row	`ButtonGroup`	Exactly one of the options is selected at a time	`Segmented`	A segmented control is a radiogroup that says which option is on; a button group is a set of acts with no selection.
		The actions do not fit, or most are rarely used	`Menu`	A menu keeps the row to one trigger.
		The buttons are unrelated actions that only happen to sit together	`Button`	Separate buttons with space between them; joining them claims a relationship that is not there.
Pick a date from a month grid	`Calendar`	The person knows the date and only needs to type it, such as a date of birth	`Input`	A typed date is faster than paging a grid back through decades.
Pick a date from a month grid	`Calendar`	The dates are events to read in order, not a value to pick	`Timeline`	A timeline shows what happened when; a calendar asks for one date.
Tick off criteria and keep the record of what was checked	`Checklist`	The ticks are independent settings or form answers	`Choice`	Checkboxes answer questions; a checklist is a record of work done.
		The items are steps in a sequence with one current step	`Stepper`	A stepper shows position in an order; a checklist can be ticked in any order.
		The system is doing the tasks and the reader is watching	`ProgressList`	A progress list reports work in progress with a spinner and failures; a checklist is ticked by hand.
		The reader is ticking off sections of a document as reviewed	`Contents`	The contents carries its own reviewed boxes beside each section link.
Tick a box, pick a radio, or turn a setting on or off	`Choice`	Each option needs a description or a figure — a plan, a delivery speed	`RadioCards`	The whole card is the label and carries a title, a note and a figure.
		The choice is between two or three views of the same thing	`Segmented`	Views are switched in a strip; radios are answers in a form.
		There are more options than fit as a short list of radios	`Select`	A select holds a long list behind one field.
		The ticks are acceptance criteria or a record of what was checked	`Checklist`	A checklist keeps done items in view as evidence, struck through rather than removed.
		Items move between two places — included and excluded, here and there	`Shelf`	A shelf shows the movement; a list of switches shows only the resulting state.
Edit code, markdown or a structured document with its shape highlighted	`CodeEditor`	The code is shown, not edited	`CodeBlock`	A code block is read-only with a copy button; an editor is a form control.
		The text is a short plain answer or a note	`Input`	A `Textarea` is enough for prose with no structure to highlight.
		The reader needs to see what changed between two versions	`Diff`	A diff marks additions and removals; an editor shows only the current text.
Pick a value from a long list by typing to narrow it	`Combobox`	A handful of options the person should see without typing	`RadioCards`	With few choices, showing them all is faster than searching.
		Several values, each removable	`TokenInput`	Tokens show each value as a removable chip; a combobox holds one.
		A list of actions or commands under a button	`Menu`	A menu runs something; a combobox sets a value.
		Searching across the whole app for a command or a place	`CommandPalette`	The palette is a dialog opened by ⌘K; a combobox is one field on a form.
		A list short enough to scan, opened from a button rather than typed into	`SelectMenu`	A select menu shows the value on a button and jumps on a letter; a combobox is a field that filters, which a short list does not need.
		A short native list in a plain form	`Select`	A native select needs no script, at the cost of an open list the platform draws.
Stack a label, a control and its hint or error as one form field	`Field`	A step has several errors and the reader needs to know how many and where	`ErrorSummary`	The summary sits at the top of the step, links to each field and takes focus; a field error only speaks for its own control.
		The problem is not about one control but about the whole form or page	`Alert`	An alert is an inline banner for the region; a field error belongs under the control it is about.
		The question is one clause of a sentence — "must stay true, because …"	`Input`	`InputGroup` with `InputAddon` attaches the connecting words to the control, so the row reads as the sentence.
Let someone attach files, by dropping them or by choosing them	`FileUpload`	The files are already stored and the reader is browsing them	`DocList`	A document library lists stored files with their type; an upload list is what is being added now.
		A file is still uploading, or failed to	`FileProgress`	A transfer row carries the bar, the percent, cancel and retry; `FileItem` is what has arrived.
		The person is pasting or writing text rather than attaching a file	`Input`	A textarea takes text; do not make someone save text to a file to submit it.
Take free text or a number typed by the person	`Input`	The value comes from a known list the person searches	`Combobox`	A combobox filters a list as you type and keeps focus in the input.
		The value is several separate labels	`TokenInput`	Tokens are removable one by one and Backspace removes the last; a comma-separated string is not.
		The text is code, markdown or a structured document	`CodeEditor`	The editor highlights the shape of what is typed and can fill the window; a textarea shows a wall of plain text.
		The value is a small count adjusted up or down	`Quantity`	The stepper puts − and + beside a real number input, so a count can be nudged or typed.
Show a secret masked, with copy, reveal and rotate	`Credential`	The person is typing a value in, or the value is not secret	`Input`	A credential displays a stored secret; an input collects one.
		There are many keys to manage, with scopes and expiry	`KeyList`	A key list shows each key by name and fingerprint without holding the secret at all.
		The text is code or a command to copy	`CodeBlock`	A code block shows its content in full with a copy control; a credential hides it.
Offer a list of actions, or one choice, behind a button	`Menu`	Narrowing a list by a dimension	`Filter`	The filter is a menu already, with the dimension on the trigger, an "any" choice and multiple values.
		A value in a form that is submitted later	`Combobox`	A combobox is a form control with a label and a value; a menu fires on choice.
		A free panel with fields or prose anchored to a button	`Popover`	A menu holds menu items only; anything else breaks its keyboard contract.
		Navigation between the app's pages	`Sidebar`	Places belong in the rail or the header where they stay visible.
		Searching every command in the app by name	`CommandPalette`	The palette filters as you type across everything; a menu lists a few things for one place.
Set a small whole-number count, stepped or typed	`Quantity`	The value is a position on a continuous range — a threshold, a weight	`Slider`	A slider shows where the value sits in its range; a stepper counts.
Set a small whole-number count, stepped or typed	`Quantity`	The number is large, free-form or has a unit	`Input`	A plain number input; nobody steps to 4,000 one press at a time.
Pick one option that needs a description and a figure to choose between	`RadioCards`	The options are short words that need no description	`Choice`	Plain radios take a line each; cards for one-word options spend space on nothing.
		The choice switches how one thing is shown	`Segmented`	A view switch is a compact strip, not a form answer.
		There are many options	`Select`	More than a handful of cards stops being a comparison.
Pick one value from a short fixed list in a form, with the native control	`Select`	The open list has to look like the product, or an option needs a note, a group heading or a disabled state you can style	`SelectMenu`	A native select's open list is drawn by the operating system and no token reaches it; the select menu is the same choice in a list that is ours.
		The list is long enough that the person should type to narrow it	`Combobox`	The combobox filters as you type; a select, native or not, only jumps on a letter.
		Two to five options that should all be visible, especially with a description each	`RadioCards`	Showing the choices beats hiding them behind a click; a radio card carries a note and a figure.
		The list is of actions, or a choice that applies at once outside a form	`Menu`	A menu runs commands and closes on choice; a select holds a form value.
		Narrowing a table or list by a dimension	`Filter`	A filter reads as the dimension, has an "any" state and can hold several values.
		Two or three views of the same thing	`Segmented`	A segmented control shows every option at once.
Pick one value from a list that is short enough to scan, with a list drawn in the system	`SelectMenu`	Too many options to scan, so the person needs to type to narrow them	`Combobox`	A combobox is a field that filters as you type; a select menu has no field, and a letter only jumps.
		A plain form where the platform's own picker is acceptable, or no script runs	`Select`	The native select needs no script and is the platform's control on touch devices; it costs a list no token reaches.
		Two to five options that should all be visible, especially with a description each	`RadioCards`	Showing the choices beats hiding them behind a click.
		A list of actions or commands under a button	`Menu`	A menu runs something and holds no value; a select menu sets one.
		Several values, each removable	`TokenInput`	A select menu holds one value; tokens show each of several as a removable chip.
Move things between two places	`Shelf`	Each item is simply on or off	`Choice`	A list of switches answers "is this on"; a shelf is for a movement the reader should see.
Move things between two places	`Shelf`	Items are ordered or grouped by state across more than two places	`Lanes`	Lanes show work moving through states; a shelf has exactly two zones the person moves things between.
Bind page keys to actions, with an off-switch and one list of every key the page binds	`Shortcuts`	Moving through a list of cards with J / K and arrows, with roving focus	`Keys`	`useListKeys` owns the focus and the tab stop in the list; bind the rest of the screen with this.
		Searching every command and place from anywhere, by a chord	`CommandPalette`	A palette is found by typing and binds ⌘K itself; a shortcut is a key someone has learned.
		Showing the shortcut beside the menu item it triggers	`Menu`	`MenuShortcut` draws it at the end of the item; the key itself is still bound here.
Set a value on a continuous range where the position matters more than the exact figure	`Slider`	The value is a count of things — copies, seats	`Quantity`	A count is stepped or typed exactly; a slider is imprecise for whole numbers.
		The exact figure matters or the range is open-ended	`Input`	A number input takes an exact value; a slider needs a known minimum and maximum.
		The figure is shown, not set	`Meter`	A meter reports a level; a slider asks for one.
List every problem on a step before it can advance, each linking to its field	`ErrorSummary`	There is one problem with one control	`Field`	`FieldError` sits under the control it is about; a summary for one error is a detour.
		The problem is with the request or the system, not the person's input	`Alert`	An alert reports a failure in the region; an error summary lists fields to fix.
		The whole step failed to load or save	`State`	The error state replaces the content with what went wrong and a way out.
Enter and remove several free labels in one field	`TokenInput`	The value is one item from a known list	`Combobox`	A combobox searches a list and holds one value.
		The values narrow a list rather than being entered on a record	`Filter`	A multiple filter ticks values of a dimension and clears with "any"; tokens are data being written.
		The labels are statuses to show, not values to edit	`Tag`	A tag reports a state and cannot be removed.

`Button`

Let someone do an action, named with a verb.

Use when

An action on the page — Save, Publish, Answer. One primary per view; secondary for equal alternatives; ghost in dense rows; destructive only for irreversible acts.
An action that navigates: ButtonLink keeps a real anchor, so it opens in a new tab and works without JavaScript.
An icon-only control: iconOnly makes aria-label required by the type.

Not when

The thing reports a state rather than doing something → Tag. A status is a tag and an action is a button; beside each other they must differ in shape, not only colour.
There are several actions on one object and not room for them all → Menu. A menu holds the secondary actions behind one trigger with the full menu keyboard contract.
A row of buttons picks one view of the same thing → Segmented. A choice between views is a radiogroup; buttons are acts, and a pressed button does not say which one is chosen.
A whole card is the link → Card. CardLink makes the card one link target instead of a card with a button inside it.

Confused with ButtonGroup, Tag, Menu, CardReact Button ButtonLinkClasses .btn

See it on the demo page

`ButtonGroup`

Set a few related actions as one adjoining row.

Use when

Two to four actions on the same object that belong together — Previous / Next, Zoom out / Zoom in.
Give every child the same variant, and name the set with label for screen readers.

Not when

Exactly one of the options is selected at a time → Segmented. A segmented control is a radiogroup that says which option is on; a button group is a set of acts with no selection.
The actions do not fit, or most are rarely used → Menu. A menu keeps the row to one trigger.
The buttons are unrelated actions that only happen to sit together → Button. Separate buttons with space between them; joining them claims a relationship that is not there.

Confused with Segmented, Button, MenuReact ButtonGroupClasses .btn-group

See it on the demo page

`Calendar`

Pick a date from a month grid.

Use when

Choosing a date where the day of the week or nearness to other dates matters — a deadline, a review date.
Dates go in and out as YYYY-MM-DD strings (toISO), never as Date objects, so a deadline cannot move a day across a time zone.

Not when

The person knows the date and only needs to type it, such as a date of birth → Input. A typed date is faster than paging a grid back through decades.
The dates are events to read in order, not a value to pick → Timeline. A timeline shows what happened when; a calendar asks for one date.

Confused with Input, Popover, TimelineReact CalendarHooks toISOClasses .calendar

See it on the demo page

`Checklist`

Tick off criteria and keep the record of what was checked.

Use when

Acceptance criteria before closing a work item: a done item recedes and is struck through, never removed — the record is part of the artifact.
purpose="manifest" for what is about to be written: checked items are the point, so they do not recede.

Not when

The ticks are independent settings or form answers → Choice. Checkboxes answer questions; a checklist is a record of work done.
The items are steps in a sequence with one current step → Stepper. A stepper shows position in an order; a checklist can be ticked in any order.
The system is doing the tasks and the reader is watching → ProgressList. A progress list reports work in progress with a spinner and failures; a checklist is ticked by hand.
The reader is ticking off sections of a document as reviewed → Contents. The contents carries its own reviewed boxes beside each section link.

Confused with Choice, Stepper, Contents, ProgressListReact Checklist ChecklistItemClasses .checklist

See it on the template

`Choice`

Tick a box, pick a radio, or turn a setting on or off.

Use when

Checkbox for independent yes/no answers, any number at once; Radio for one of a few short options in a form.
Switch for a setting that takes effect on its own — on or off, not selected or unselected.
Always wrap the control and its text in Choice: the label is the hit target, so the whole row is clickable at 44px.

Not when

Each option needs a description or a figure — a plan, a delivery speed → RadioCards. The whole card is the label and carries a title, a note and a figure.
The choice is between two or three views of the same thing → Segmented. Views are switched in a strip; radios are answers in a form.
There are more options than fit as a short list of radios → Select. A select holds a long list behind one field.
The ticks are acceptance criteria or a record of what was checked → Checklist. A checklist keeps done items in view as evidence, struck through rather than removed.
Items move between two places — included and excluded, here and there → Shelf. A shelf shows the movement; a list of switches shows only the resulting state.

Confused with RadioCards, Segmented, Select, Checklist, ShelfReact Choice ChoiceHint Checkbox Radio SwitchClasses .choice .checkbox .radio .switch

See it on the demo page

`CodeEditor`

Edit code, markdown or a structured document with its shape highlighted.

Use when

Editing a markdown or JSON document, a config, a query — a textarea with highlighting painted under it, so undo, IME and assistive tech work as normal.
Editing a long governed document: full fills the window, and Escape leaves it through the caller's onLeaveFull.

Not when

The code is shown, not edited → CodeBlock. A code block is read-only with a copy button; an editor is a form control.
The text is a short plain answer or a note → Input. A Textarea is enough for prose with no structure to highlight.
The reader needs to see what changed between two versions → Diff. A diff marks additions and removals; an editor shows only the current text.

Confused with CodeBlock, Input, DiffReact CodeEditorClasses .code-editor

No demo page yet.

`Combobox`

Pick a value from a long list by typing to narrow it.

Use when

An owner from forty people, a code from hundreds — too many to scan, easy to type.
The list has to look like the rest of the system and work the same on keyboard and touch; focus stays in the input.
allowCustom when the person may enter a value the list does not hold.

Not when

A handful of options the person should see without typing → RadioCards. With few choices, showing them all is faster than searching.
Several values, each removable → TokenInput. Tokens show each value as a removable chip; a combobox holds one.
A list of actions or commands under a button → Menu. A menu runs something; a combobox sets a value.
Searching across the whole app for a command or a place → CommandPalette. The palette is a dialog opened by ⌘K; a combobox is one field on a form.
A list short enough to scan, opened from a button rather than typed into → SelectMenu. A select menu shows the value on a button and jumps on a letter; a combobox is a field that filters, which a short list does not need.
A short native list in a plain form → Select. A native select needs no script, at the cost of an open list the platform draws.

Confused with SelectMenu, Select, Menu, TokenInput, CommandPaletteReact ComboboxClasses .combobox .listbox

See it on the demo page

`Field`

Stack a label, a control and its hint or error as one form field.

Use when

Every form control that needs a visible label: FieldLabel, the control, then FieldHint or FieldError.
A field that is optional: FieldLabel optional adds a quiet marker rather than starring what is required.
A validation message for one control: FieldError is announced when it changes.

Not when

A step has several errors and the reader needs to know how many and where → ErrorSummary. The summary sits at the top of the step, links to each field and takes focus; a field error only speaks for its own control.
The problem is not about one control but about the whole form or page → Alert. An alert is an inline banner for the region; a field error belongs under the control it is about.
The question is one clause of a sentence — "must stay true, because …" → Input. InputGroup with InputAddon attaches the connecting words to the control, so the row reads as the sentence.

Confused with Input, ErrorSummary, ChoiceReact Field FieldLabel FieldHint FieldErrorClasses .field

See it on the demo page

`FileUpload`

Let someone attach files, by dropping them or by choosing them.

Use when

Attaching evidence or documents to a form: a drop zone over a real file input, so the keyboard and screen readers can use it without drag.
Listing what was attached: FileList with a FileItem per file, its size, and an error when one fails.

Not when

The files are already stored and the reader is browsing them → DocList. A document library lists stored files with their type; an upload list is what is being added now.
A file is still uploading, or failed to → FileProgress. A transfer row carries the bar, the percent, cancel and retry; FileItem is what has arrived.
The person is pasting or writing text rather than attaching a file → Input. A textarea takes text; do not make someone save text to a file to submit it.

Confused with DocList, Field, FileProgressReact FileUpload FileList FileItemClasses .dropzone .file-list .file-item

See it on the demo page

`Input`

Take free text or a number typed by the person.

Use when

A single line of text, an email, a number: Input inside a Field. invalid drives both the border and aria-invalid.
Several lines of prose: Textarea.
A field that is one clause of a sentence: InputGroup with InputAddon for the words the person does not type; give the input its own aria-label.

Not when

The value comes from a known list the person searches → Combobox. A combobox filters a list as you type and keeps focus in the input.
The value is several separate labels → TokenInput. Tokens are removable one by one and Backspace removes the last; a comma-separated string is not.
The text is code, markdown or a structured document → CodeEditor. The editor highlights the shape of what is typed and can fill the window; a textarea shows a wall of plain text.
The value is a small count adjusted up or down → Quantity. The stepper puts − and + beside a real number input, so a count can be nudged or typed.

Confused with Field, Combobox, TokenInput, CodeEditor, SelectReact Input InputAddon InputGroup TextareaClasses .input .textarea

See it on the demo page

`Credential`

Show a secret masked, with copy, reveal and rotate.

Use when

An API key, token or webhook secret the person may copy or rotate; the masked value is a substitute string, not the secret.
Copy works without reveal, so a key never has to be on screen to be used.
A write-once secret: pass neverReveal and the reveal control is gone.

Not when

The person is typing a value in, or the value is not secret → Input. A credential displays a stored secret; an input collects one.
There are many keys to manage, with scopes and expiry → KeyList. A key list shows each key by name and fingerprint without holding the secret at all.
The text is code or a command to copy → CodeBlock. A code block shows its content in full with a copy control; a credential hides it.

Confused with Input, KeyList, CodeBlockReact CredentialClasses .credential

See it on the demo page

`Menu`

Offer a list of actions, or one choice, behind a button.

Use when

Secondary actions on a row or a page — Rename, Duplicate, Archive — behind a "More" button; put a destructive one last.
An account menu, with MenuIdentity naming who is signed in, and MenuSub for a nested group.
One choice that applies at once — sort order, density — with selected on each item; choosing closes it.

Not when

Narrowing a list by a dimension → Filter. The filter is a menu already, with the dimension on the trigger, an "any" choice and multiple values.
A value in a form that is submitted later → Combobox. A combobox is a form control with a label and a value; a menu fires on choice.
A free panel with fields or prose anchored to a button → Popover. A menu holds menu items only; anything else breaks its keyboard contract.
Navigation between the app's pages → Sidebar. Places belong in the rail or the header where they stay visible.
Searching every command in the app by name → CommandPalette. The palette filters as you type across everything; a menu lists a few things for one place.

Confused with Filter, Combobox, Select, Popover, CommandPaletteReact Menu MenuIdentity MenuItem MenuLabel MenuSeparator MenuShortcut MenuSubClasses .menu

See it on the demo page

`Quantity`

Set a small whole-number count, stepped or typed.

Use when

How many of an item — copies in a basket, seats on a plan — between a min and a max.
The value sits in a real number input, so typing 12 beats pressing + eleven times.

Not when

The value is a position on a continuous range — a threshold, a weight → Slider. A slider shows where the value sits in its range; a stepper counts.
The number is large, free-form or has a unit → Input. A plain number input; nobody steps to 4,000 one press at a time.

Confused with Slider, InputReact QuantityClasses .qty

See it on the template

`RadioCards`

Pick one option that needs a description and a figure to choose between.

Use when

A choice where the label alone does not settle it — a delivery speed with its price, a plan with what it includes.
Wrap in a fieldset with a legend: the group needs a name. columns sets short options side by side.

Not when

The options are short words that need no description → Choice. Plain radios take a line each; cards for one-word options spend space on nothing.
The choice switches how one thing is shown → Segmented. A view switch is a compact strip, not a form answer.
There are many options → Select. More than a handful of cards stops being a comparison.

Confused with Choice, Segmented, SelectReact RadioCards RadioCardClasses .radio-cards .radio-card

See it on the template

`Select`

Pick one value from a short fixed list in a form, with the native control.

Use when

A form value from a short, familiar list — a country, a currency — where the platform picker is acceptable and the form submits natively.
Inside a Field with a label; invalid sets aria-invalid.

Not when

The open list has to look like the product, or an option needs a note, a group heading or a disabled state you can style → SelectMenu. A native select's open list is drawn by the operating system and no token reaches it; the select menu is the same choice in a list that is ours.
The list is long enough that the person should type to narrow it → Combobox. The combobox filters as you type; a select, native or not, only jumps on a letter.
Two to five options that should all be visible, especially with a description each → RadioCards. Showing the choices beats hiding them behind a click; a radio card carries a note and a figure.
The list is of actions, or a choice that applies at once outside a form → Menu. A menu runs commands and closes on choice; a select holds a form value.
Narrowing a table or list by a dimension → Filter. A filter reads as the dimension, has an "any" state and can hold several values.
Two or three views of the same thing → Segmented. A segmented control shows every option at once.

Confused with SelectMenu, Combobox, Menu, RadioCards, Filter, SegmentedReact SelectClasses .select

See it on the demo page

`SelectMenu`

Pick one value from a list that is short enough to scan, with a list drawn in the system.

Use when

One value from a list of a few to a few dozen — a client, a status, a region — where the open list has to look like the rest of the product, not the operating system.
Options that need a note under them to be told apart, grouped options, or options that are there but cannot be chosen yet. A native select can carry none of these.
Keys: Enter, Space or ↓ open on the chosen option; a letter jumps to the option that starts with it; Escape closes with no change and focus goes back to the button. name submits the value with a native form.

Not when

Too many options to scan, so the person needs to type to narrow them → Combobox. A combobox is a field that filters as you type; a select menu has no field, and a letter only jumps.
A plain form where the platform's own picker is acceptable, or no script runs → Select. The native select needs no script and is the platform's control on touch devices; it costs a list no token reaches.
Two to five options that should all be visible, especially with a description each → RadioCards. Showing the choices beats hiding them behind a click.
A list of actions or commands under a button → Menu. A menu runs something and holds no value; a select menu sets one.
Several values, each removable → TokenInput. A select menu holds one value; tokens show each of several as a removable chip.

Confused with Select, Combobox, Menu, RadioCardsReact SelectMenuHooks useListboxClasses .select-menu

See it on the demo page

`Shelf`

Move things between two places.

Use when

Taking items out of one place and putting them in another — included and excluded, in scope and out.
Drag by the grip, or Space, arrows, Space by keyboard; the row itself opens the item. A fixed item says why it cannot move.
layout="stack" when the shelf lives in a narrow rail.

Not when

Each item is simply on or off → Choice. A list of switches answers "is this on"; a shelf is for a movement the reader should see.
Items are ordered or grouped by state across more than two places → Lanes. Lanes show work moving through states; a shelf has exactly two zones the person moves things between.

Confused with Choice, Lanes, ItemReact ShelfClasses .shelf

No demo page yet.

`Shortcuts`

Bind page keys to actions, with an off-switch and one list of every key the page binds.

Use when

A screen people work through all day — next, done, assign — where one key per action saves time: useShortcuts([{ key: 'j', does: 'Next item', run }]). Keys stand down while typing in a field, with Ctrl, ⌘ or Alt held, and under a dialog.
Single-key shortcuts have to be possible to turn off (WCAG 2.1.4). Wrap the app in ShortcutsProvider, which stores the switch per person, and show ShortcutHelp — every registered key and the switch — behind a visible "?" button, not only behind the ? key.
Escape that closes one thing at a time — a popover, then a draft, then the search — with closeTopLayer, still working inside a search field.

Not when

Moving through a list of cards with J / K and arrows, with roving focus → Keys. useListKeys owns the focus and the tab stop in the list; bind the rest of the screen with this.
Searching every command and place from anywhere, by a chord → CommandPalette. A palette is found by typing and binds ⌘K itself; a shortcut is a key someone has learned.
Showing the shortcut beside the menu item it triggers → Menu. MenuShortcut draws it at the end of the item; the key itself is still bound here.

Confused with Keys, CommandPalette, MenuReact ShortcutsProvider ShortcutHelpHooks useShortcuts useSingleKeyShortcuts useShortcutGroups closeTopLayer

See it on the demo page

`Slider`

Set a value on a continuous range where the position matters more than the exact figure.

Use when

A threshold, a weight, a confidence level — somewhere on a known range, with the current value shown beside the label.
Use display for units — "62%", "3 days". It is a native range input, so keyboard stepping and form participation come free.

Not when

The value is a count of things — copies, seats → Quantity. A count is stepped or typed exactly; a slider is imprecise for whole numbers.
The exact figure matters or the range is open-ended → Input. A number input takes an exact value; a slider needs a known minimum and maximum.
The figure is shown, not set → Meter. A meter reports a level; a slider asks for one.

Confused with Quantity, Input, MeterReact SliderClasses .slider

See it on the demo page

`ErrorSummary`

List every problem on a step before it can advance, each linking to its field.

Use when

Validation on Next in a multi-step form: useStepValidation runs native constraint validation (plus your own validate) and moves focus to the summary.
A long step where the reader needs to know how many problems there are and where.

Not when

There is one problem with one control → Field. FieldError sits under the control it is about; a summary for one error is a detour.
The problem is with the request or the system, not the person's input → Alert. An alert reports a failure in the region; an error summary lists fields to fix.
The whole step failed to load or save → State. The error state replaces the content with what went wrong and a way out.

Confused with Field, Alert, FlowReact ErrorSummaryHooks useStepValidationClasses .error-summary

No demo page yet.

`TokenInput`

Enter and remove several free labels in one field.

Use when

Labels, keywords or recipients typed by the person: each becomes a removable token; Backspace on an empty field removes the last.
Each × is a real button, so a token can be removed by keyboard.

Not when

The value is one item from a known list → Combobox. A combobox searches a list and holds one value.
The values narrow a list rather than being entered on a record → Filter. A multiple filter ticks values of a dimension and clears with "any"; tokens are data being written.
The labels are statuses to show, not values to edit → Tag. A tag reports a state and cannot be removed.

Confused with Combobox, Input, Tag, FilterReact TokenInputClasses .token-input

See it on the template

Other guides: Screens · Overlays · Status and feedback · Navigation · Data · Reading · Agents and live work

Generated from the when.ts beside each component — the same data the Claude Code plugin reads.