UX Patterns Guide
UI + UX Search, Browse, And Discovery established

Search scope selector

Provide a visible, labelled scope selector that chooses the searchable corpus, preserves or explicitly clears the query, updates counts and result summaries with each scope, and explains unavailable or permission-limited scopes.

Open in lab Compare alternatives
Decision first

Choose this pattern when the problem matches

Use when

  • The same query can search different repositories, sites, workspaces, spaces, channels, result types, teams, or organization-wide indexes.
  • The user's current location is a useful default but not always the desired search coverage.
  • Broader or narrower search scopes materially change result count, ranking, privacy, or performance.
  • Users frequently recover from wrong-scope searches by broadening or narrowing where the system looks.

Avoid when

  • There is only one searchable corpus and scope selection would be decorative.
  • Users need ordinary filtering within one result set rather than changing where the query runs.
  • The choice is really navigation between product sections, not a search corpus.
  • The corpus distinction is technical and cannot be explained in user-facing terms.
  • Permission rules make a scope unsafe to expose or impossible to explain.

Problem it prevents

Users search the wrong corpus when products have multiple searchable locations, content types, repositories, spaces, conversations, sites, or permission boundaries but the UI hides where the query will run.

Pattern anatomy

What a strong implementation has to make clear

User need

The product can search across different sites, spaces, repositories, channels, conversations, teams, result types, hubs, tenants, or organization-wide indexes.

Pattern promise

Provide a visible, labelled scope selector that chooses the searchable corpus, preserves or explicitly clears the query, updates counts and result summaries with each scope, and explains unavailable or permission-limited scopes.

Required state

Default scope state based on current location or product-wide policy.

Recovery path

Users search only the current site, repository, or channel while believing they searched everything.

Access contract

Use a labelled fieldset, radio group, select, or tablist only when the semantics match the scope interaction.

Quality bar

The difference between expert and weak execution

Strong implementation

Specific, visible, recoverable

  • A knowledge search field includes scope buttons for All knowledge, Current workspace, Cases, and People with the active scope repeated above results.
  • A repository search box labels the current scope as This repository and offers All repositories without hiding the repo qualifier in placeholder text.
  • A user searches appeal in Current workspace, switches to All knowledge, and sees the same query rerun with a larger result count and broader source summary.
  • A user chooses People and the result list changes to people records while the query remains editable and the search input keeps its value.
Weak implementation

Vague, hidden, hard to recover from

  • The placeholder says Search this site, but after typing only a generic magnifying glass remains and the result page no longer names the scope.
  • The product silently searches the current channel while the user assumes all workspace messages were searched.
  • Switching from This repository to All GitHub clears the query and leaves users unsure whether anything ran.
  • A Files tab looks selected after the query, but users cannot tell whether future searches will search only files or all content.
UI guidance
  • Render the active search scope near the search input and result summary, using user-facing corpus names such as Current workspace, All knowledge, This repository, or People.
  • Expose scope choices as radios, segmented buttons, a labelled select, or clearly labelled result-source tabs, and show result counts or availability when scope changes affect expected coverage.
UX guidance
  • Use a search scope selector when the same query can search meaningfully different content sources and users need to control where the system looks.
  • Preserve the typed query when scope changes unless the query syntax is incompatible, and explain when a broader or narrower scope is unavailable because of permissions or product rules.
Implementation contract

What the implementation must handle

States

  • Default scope state based on current location or product-wide policy.
  • Explicitly selected scope state before the query is submitted.
  • Submitted query state with scope name and result count.
  • Scope changed state where the query is preserved and results rerun.

Interaction

  • Selecting a scope changes the corpus searched, not merely the visual grouping of existing results.
  • The search input, result count, result list, and result summary all update from the same query and scope state.
  • Changing scope preserves the current query unless the user confirms clearing it or the query cannot run in the new scope.
  • Changing scope resets pagination and clears stale highlights or result selections that belonged to the previous corpus.

Accessibility

  • Use a labelled fieldset, radio group, select, or tablist only when the semantics match the scope interaction.
  • Include the active scope name in the search form accessible name or adjacent text, not only in visual styling.
  • Announce result-count changes after scope changes through the same status region used for search results.
  • Do not rely on placeholder text as the only scope label.

Review

  • Can users tell where the next search will run before they submit it?
  • After results load, does the result summary name both the query and the active scope?
  • What happens to query text, pagination, filters, highlights, and selected results when scope changes?
  • Are current-location defaults clear enough when users may expect product-wide search?
Interactive lab

Inspect the states before you copy the pattern

Choose where search runs

Switch search scope, keep the query visible, and check whether result counts, unavailable scopes, and summaries update together.

Search scope selector
Interactive demo is ready

Launch the live UI/UX lab when you want to inspect states, keyboard behavior, and common failure modes.

State To Inspect

Default scope state based on current location or product-wide policy.

Keyboard / Access

Tab reaches the scope selector before Search when scope changes the next submitted query.

Avoid Generating

Putting scope only in placeholder text, which disappears when users type.
Evidence trail

Source-backed claims behind this guidance

GitHub repository search scope

GitHub Docs - checked

GitHub documents automatically constraining repository-context searches with a repo qualifier.

Slack Search in Slack

Slack Help Center - checked

Slack documents conversation-scoped search modifiers, result type switches, filters, and current-conversation search shortcuts.

Confluence Cloud search for content

Atlassian Support - checked

Confluence documents search focus controls such as spaces, pages under, content type, and titles-only search.

Full agent/debug reference

Problem Context

  • The product can search across different sites, spaces, repositories, channels, conversations, teams, result types, hubs, tenants, or organization-wide indexes.
  • A user's current location creates a useful default scope but may not match the user's intent.
  • Broader scopes can expose more results, take longer, change ranking, or be limited by permissions.

Selection Rules

  • Choose search scope selector when users need to decide where the search runs before interpreting results.
  • Show the active scope before submission when the default could be confused with a broader or narrower corpus.
  • Repeat the active scope in the result heading, result count, URL state, or applied criteria summary after submission.
  • Preserve the typed query when users switch scope if the query syntax works in the new corpus.
  • Reset pagination to the first page when scope changes, because the result set is different even when the query text is the same.
  • Use permission-aware scope choices so unavailable broad scopes are disabled with explanations or omitted according to security policy.
  • Use user-facing content names rather than backend index, tenant, vertical, or source IDs.
  • Distinguish result-type tabs from pre-query search scope when both are present, because switching Messages to Files after search is not always the same as searching only files next time.
  • Use filter panel after scope selection when users need attribute constraints within the chosen corpus.
  • Use advanced search when users need boolean logic, fielded query syntax, or multiple clauses rather than a small set of named corpora.

Required States

  • Default scope state based on current location or product-wide policy.
  • Explicitly selected scope state before the query is submitted.
  • Submitted query state with scope name and result count.
  • Scope changed state where the query is preserved and results rerun.
  • Unavailable or permission-limited scope state with explanation.
  • No-results-in-this-scope state with path to broaden or change scope.
  • Mobile compact state where the active scope remains visible near the search input.
  • Deep-linked state where query and scope restore from the URL or saved view.
  • Incompatible query syntax state when a qualifier or field only works in one scope.

Interaction Contract

  • Selecting a scope changes the corpus searched, not merely the visual grouping of existing results.
  • The search input, result count, result list, and result summary all update from the same query and scope state.
  • Changing scope preserves the current query unless the user confirms clearing it or the query cannot run in the new scope.
  • Changing scope resets pagination and clears stale highlights or result selections that belonged to the previous corpus.
  • Scope choices remain keyboard reachable and have accessible names that include what content they search.
  • Unavailable scopes explain whether the reason is permission, product plan, guest mode, indexing delay, or no content source.
  • When a scope is encoded as query syntax, the visible UI still explains it in plain language.
  • Deep links, saved searches, and browser history restore both query and scope.

Implementation Checklist

  • Define the canonical scope IDs and map each one to a user-facing label, content source, permission rule, and result route.
  • Keep query, scope, filters, sort, and result type as separate state so changing one does not silently mutate the others.
  • Place the active scope in or next to the search form and repeat it in the result summary.
  • Persist scope in URL parameters, route state, or saved search definitions when users need shareable or resumable results.
  • Reset pagination and stale selected-result state whenever scope changes.
  • Validate whether typed query qualifiers are compatible with the selected scope and offer repair copy when they are not.
  • Disable, hide, or explain broad scopes that the current user cannot search.
  • Test current-location defaults, broadening actions, mobile presentation, keyboard order, result counts, no-results recovery, and permission-limited users.

Common Generated-UI Mistakes

  • Putting scope only in placeholder text, which disappears when users type.
  • Using tabs as scope selectors without saying whether future searches will use the selected tab.
  • Calling scope choices filters even though they change the corpus before attribute filtering begins.
  • Changing scope while leaving the previous result count, highlights, or selected result active.
  • Showing broad organization scope to users who cannot search it.
  • Using internal source names or index IDs as menu labels.

Critique Questions

  • Can users tell where the next search will run before they submit it?
  • After results load, does the result summary name both the query and the active scope?
  • What happens to query text, pagination, filters, highlights, and selected results when scope changes?
  • Are current-location defaults clear enough when users may expect product-wide search?
  • Are unavailable broad scopes explained without implying zero results?
  • Are result-type tabs, filters, and scope choices visually and semantically distinct?
Accessibility
  • Use a labelled fieldset, radio group, select, or tablist only when the semantics match the scope interaction.
  • Include the active scope name in the search form accessible name or adjacent text, not only in visual styling.
  • Announce result-count changes after scope changes through the same status region used for search results.
  • Do not rely on placeholder text as the only scope label.
  • Make disabled scopes programmatically disabled and provide adjacent explanatory text when users need to know why they are unavailable.
  • Keep scope controls reachable before the submit action when scope affects what the search will do.
Keyboard Behavior
  • Tab reaches the scope selector before Search when scope changes the next submitted query.
  • Arrow keys move among radio or segmented scope choices when those semantics are used.
  • Enter submits the current query and active scope together.
  • Changing scope after results load moves focus predictably to the updated result summary or leaves it on the selected scope with an announcement.
  • Escape closes compact scope menus without changing the active scope.
  • Browser back and forward restore both query and selected scope.
Variants
  • This site vs all sites
  • Current repository vs all repositories
  • Current channel vs all conversations
  • Current workspace vs all workspaces
  • People, files, messages, and pages scopes
  • Hub search scope
  • Organization search scope
  • Search titles only scope
  • Permission-limited scope
  • Deep-linked scoped search

Verification

Last verified: