Connect a clearly scoped query to useful results and recoverable request states.
Search helps people find information by expressing what they need. Give it a clear scope, such as projects in a workspace, and keep that scope visible as the query changes. Use Filtering for known attributes that narrow a result set.
Use a labeled TextField with type="search". The clearable option adds a clear action; provide a useful clearLabel, such as “Clear project search.” The component owns text entry and clear interaction, not indexing, matching, ranking, suggestions, or result fetching.
Compose results with semantic links or a supported List presentation, loading with ProgressIndicator, and known absence with EmptyState. Preserve ordinary navigation semantics for results that open another page. TextField is not an autocomplete combobox; adding a suggestions popup requires a separate, accessible application implementation.
Figure in preparation
Search: interaction sequence
Query changes, request ordering, and result states.
For explicit submission, use a native form and one submit handler. TextField's onSubmit also runs on Enter and does not prevent native form submission. Do not attach the same request to both paths.
For search as people type, choose debounce and request cancellation according to the actual data source. Ignore stale responses so an earlier query cannot overwrite later results. Keep typed text responsive while requests run and account for text composition input before launching searches.
Distinguish an untouched search, an empty query, pending results, matching results, no matches, and a request error. For a project search, an empty query can restore the normal project list; document a different meaning if the product uses one.
Clearing an enabled, editable, nonempty clearable TextField requests an empty value, calls onClear, and refocuses the input. Escape also clears when that action is available. The application must accept the controlled value update and decide what happens to results and requests.
Keep the query after a failed search. Offer retry and state whether any visible results belong to the previous successful query. Do not show “No projects found” when the request failed or has not completed.
Name the scope in the label, such as “Search projects.” Use placeholder text for an example rather than the only explanation. Result titles should identify the destination; snippets should explain why it may be relevant without repeating the same title.
Show active filters near results and provide a route to remove them. Store or display search history only when that behavior is appropriate for the application and its users.
Keep focus in the field while results update unless the person explicitly navigates into them. Announce a concise result count or error through application-owned status content; avoid announcing the entire list on each keystroke.
Test Enter submission, clearing, IME composition, result links, and keyboard access to recovery. Keep the result region and search scope understandable without relying on visual proximity alone.
See TextField, List, Link, ProgressIndicator, and EmptyState. Read Loading for request feedback.