# Typeahead

> Moving to an item by typing the beginning of its name.

Typeahead moves focus to an item when people type the beginning of its name. It
makes long, ordered collections quick to traverse without a pointer.

## Best practices

**Match the beginning of each name, ignoring case and accents.** People type what
they read, without capitals or diacritics: typing "zu" should find "Zürich".

**Treat quick typing as one query, and a pause as the start of another.**
Characters typed in quick succession accumulate; after about a second without
typing, the next character begins a new search.

**Cycle on a repeated character.** Pressing the same letter again moves to the
next item that begins with it, so a single key steps through a section of the
collection.

**End the query when focus leaves.** A query belongs to one visit to the
collection. What is typed on returning starts a new one, however soon.

**Read no more than the search needs.** In a long collection, look at each
item's name only as the search reaches it, and stop at the match.

**Let a query contain spaces.** Once a query has begun, Space belongs to it, so
names of several words can be typed. Before a query begins, Space keeps its usual
meaning.

**Match the name, not the decoration.** When an item's visible label includes an
icon, a count or a status, match against the name alone.

**Order the collection so typeahead is predictable.** In an alphabetical or
otherwise familiar order, typing lands where people expect. In an arbitrary
order it remains a shortcut, but cannot be relied on.

## 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.
- A character finds the next item starting with it, after the current one.
- The search comes round past the end.
- A longer query may match the current item.
- A repeated character cycles like a single one.
- Case and accents are ignored.
- No match is no match.
- Among ten thousand items, a query reads the text of only those up to its match.

## Reference implementation

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