组件 · 搜索

Search

The search trigger in the web top bar, and the parts of search results — rows for places and people, message and thread hits, grouped by kind with the matched words marked.

稳定也叫 SearchTrigger

import { Search } from "@botiverse/raft-ui";

本页尚未翻译

译文完成之前，这里显示英文原文。阅读英文版

Search is a field, a few filters and results grouped by kind. Places and people are rows; messages are hits that say who, where and when, with the matched words as small yellow stickers. On the web, search opens from the search field in the top bar (SearchTrigger); on a phone it is the Search tab, with the field in the tab's top bar.

search/compositions/search-panel

When to use

Situation	Use
Finding a place, a person or a message to go to	Search
Finding a value to fill in, inside a popup	A select with search (ComboboxSelect) or a Combobox
Narrowing a list that is already on screen	A filter (Choosing a component)

Anatomy

Trigger

SearchTrigger: the top bar's search field. It looks like a field and is a button that opens the search dialog. Like every field it doesn't hover; a press lays the medium tier (Hover and press).
- A search icon, then SearchTriggerLabel (the placeholder, Search Raft), then SearchTriggerShortcut (⌘K) at the right end. The label truncates first.

search/compositions/search-trigger

Results

SearchShellRoot: the search surface, with SearchShellFilters (the row of filters) and SearchShellViewport (the scrolling results).
SearchResultsSummary: one line about the results: "Searching for “launch”…".
SearchResultsSection: one kind of result, with SearchResultsSectionHeading (Messages 13) and SearchResultsList.
SearchEntityResult: a channel, a person or an agent. It follows the layout of a ListRow: SearchEntityResultLeading (a SearchEntityResultIcon or an avatar, with an optional SearchEntityResultActivity light), and SearchEntityResultContent with SearchEntityResultHeader, SearchEntityResultTitle and SearchEntityResultDescription.
SearchMessageResult: a message. SearchMessageResultHeader holds SearchMessageResultSender (who), SearchMessageResultMeta (where), SearchMessageResultThreadMeta (in a thread) and SearchMessageResultTimestamp (when); SearchMessageResultBody holds the excerpt, with each match in SearchMessageResultMatch.
SearchThreadResult: a thread with several hits: SearchThreadResultHeader (SearchThreadResultMeta, SearchThreadResultTimestamp, SearchThreadResultTitle) and SearchThreadResultMessages, a list of SearchThreadMessageResult.

search/compositions/search-preview

States

State	Use for
`selected` on a result	The keyboard highlight: `brand-soft`, as in menus (States)
Menu open (`data-popup-open` on a result)	`fill-subtle`, the same subtle tier as the hover, so the result the menu acts on stays marked; a `selected` result keeps `brand-soft` (Hover and press)
`muted` on an entity's title and description	A place the person can't post in any more, such as an archived channel
Loading	A summary line and skeletons in the shape of the results (Feedback)
No results	An EmptyState that says how to widen the search

search/compositions/search-muted-entity

search/compositions/search-loading

search/compositions/search-no-results

Behavior

On a phone, search is the Search tab, and the field is in its navigation row (Page structure). Its keyboard, its kept state, opening a result and searching inside one place are in Navigation.
Give the field the same margin on both sides, the content edge of what is under it (16px on a phone). Don't leave a narrower edge on one side for an icon.
On the web, open search from the top bar's field as a centered dialog, 720px wide, whose top edge covers the top bar's field, so the field seems to grow into it. It has the scrim and no animation, like every centered overlay (Choosing a component).
Group results by kind (Conversation): places and people first, then messages.
Show the scope, the sender, the place and the time range as filters in the filter row, each a select or combobox.
Open a selected result in the side panel (Conversation). A hit in a thread opens that thread directly.
Move the keyboard highlight from the field into the results with the Down arrow, and open the highlighted result with Enter.

Content

Make the excerpt of a message at most 2 lines, with the matched words in SearchMessageResultMatch.
Write the no-results state as what wasn't found and how to widen it: "No results for “launch”", "Try another word or remove a filter."
Write the trigger's placeholder as what it searches: Search Raft.

Accessibility

The parts render native elements through Base UI's useRender; no Base UI primitive is involved. Results are buttons by default; pass a link with render for a result that navigates.
SearchTrigger is a button named by its label. It opens a Dialog; give the dialog a title and the field inside it an accessible name (aria-label="Search").
Put the field and its filters in an element with role="search", and give the clear button aria-label="Clear search".
selected is visual only. When you move a keyboard highlight through the results, keep focus on the field and point to the highlighted result with aria-activedescendant, or move focus to it.
Give an entity's activity light a name: role="img" and aria-label="Active".
SearchMessageResultMatch is a mark, so matches are announced where the reader supports it.