> For the complete documentation index, see [llms.txt](https://docs.notionapps.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.notionapps.com/screens-and-components/types-of-screens/everyday-chrome-screens/search.md).

# Search

The **Search** screen gives end users one place to look across the app’s linked databases. Instead of opening several lists and guessing where a record lives, users can search by keyword, revisit recent searches, and open matching records directly from the results.

Use `Search` when browsing is too slow and the user’s real job is “I know roughly what I’m looking for, help me find it.” This is especially valuable in apps that span multiple sheets.

{% hint style="info" %}
**Who this guide is for**\
Makers whose users search across multiple databases and need one predictable lookup surface. This guide explains every Search option in prose, including the partially exposed scope behavior that the runtime already supports.
{% endhint %}

## What the screen is for

### Use Search when

* Users need to find a request, asset, order, client, or task by keyword
* Users repeat common lookups and benefit from recent searches
* Search results should open the matching record screen

### Do not use it when

* You only need one list’s built-in filters
* Users need a shared team inbox: use **Work Queue**
* Users need a personal “needs me” feed: use **My Queue**
* You want a scanner-only flow inside a single list: keep that flow on the list

## What users see in the live app

The runtime provides:

* A search field with the placeholder `Search across databases`
* A `Search` button
* Recent searches stored locally for the current app
* Result rows with a title and optional subtitle
* A no-query empty state and a separate no-match state

| Default                        | Value                                                               |
| ------------------------------ | ------------------------------------------------------------------- |
| Display title                  | Search                                                              |
| Empty title                    | Search your app                                                     |
| Empty description              | Find records across linked databases. Try a keyword or scan a code. |
| Empty action label             | Scan                                                                |
| Sheet scope (`searchSheetIds`) | Empty = all linked databases                                        |
| Entitlement                    | None                                                                |

## Add Search in the builder

1. Open **Screens → + New Screen**.
2. Choose a Notion database as the context anchor.
3. Under **Everyday chrome**, select **Search**.
4. Click **Done**.
5. Configure the empty-state copy.
6. Place Search in navigation where users can reach it quickly.
7. Publish before testing in the live app.

![Builder configuration for this screen](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2F3MJXclbT6b6dZtOtdaqv%2Feveryday-chrome__search__00-builder-hero.jpg?alt=media)

![End-user preview of this screen](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2FW8SPmpa57McQl0Iq2pOB%2Feveryday-chrome__search__09-preview-closeup.jpg?alt=media)

## Complete Builder Options Reference

Search uses the same lightweight chrome config panel as the other Everyday chrome screens. The visible controls are minimal, but the runtime behavior is important, especially for search scope and result navigation.

![Annotated builder screenshot: Chrome config](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2FqSGH9whsTKZfJE4maXcL%2Feveryday-chrome__search__01-section-chrome-config.jpg?alt=media)

### Screen identity

This section explains the built-in behavior that makes Search different from a list or details screen.

#### Screen type

**What it does:**\
This identifies the screen as `Search` and tells the runtime to load the cross-database search experience with recents and result rows.

**How to use it:**\
Choose `Search` from the Everyday chrome picker when the user job is lookup, not browsing. Do not expect normal list filters, table layouts, or form configuration on this screen.

**Why / recommended default:**\
The recommendation is to use Search only when users truly need one search box across the app. A common mistake is adding Search as a substitute for a missing list screen, which creates a poor experience for users who need browsing rather than lookup.

#### Title and description defaults

**What it does:**\
Search starts with registry-provided display text and empty-state framing.

**How to use it:**\
Keep the navigation label simple, usually `Search`. The value of this screen comes from being easy to spot, not from a clever name.

**Why / recommended default:**\
Users expect the search surface to be obvious. A common mistake is renaming it to something branded or technical, which makes a core utility harder to find.

### Empty state

These fields shape the screen before the user starts typing.

#### Empty state title

![Annotated builder screenshot: Empty state title](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2Frf8gQ5iyII5B3njTubzo%2Feveryday-chrome__search__02-section-empty-state-title.jpg?alt=media)

**What it does:**\
This is the heading shown when the search field is empty and no results are being shown.

**How to use it:**\
Use wording that encourages the user to start searching. `Search your app` is a strong default because it is direct and broad enough for many use cases.

**Why / recommended default:**\
The screen often opens in this state, so the title should teach the behavior quickly. A common mistake is making the title too specific to one database when Search is meant to work across many.

#### Empty state description

![Annotated builder screenshot: Empty state description](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2FEWoN71Y2XB0Uui4iMgXq%2Feveryday-chrome__search__03-section-empty-state-description.jpg?alt=media)

**What it does:**\
This explains what kinds of searches the user can perform before they enter a query.

**How to use it:**\
Mention the types of data users can find and, if relevant, that they can use a keyword or scan path. Keep it short enough to be useful on mobile.

**Why / recommended default:**\
The recommended default already teaches two useful ideas: the search is cross-database, and scan-related lookup may also be part of the app. A common mistake is leaving the description generic, which misses a chance to set expectations.

#### Empty action label

**What it does:**\
The registry default for Search includes the action label `Scan`.

**How to use it:**\
Be aware that this is a runtime default, not a fully exposed builder field in the chrome config panel. In other words, you should not count on being able to tune this label from the panel today.

**Why / recommended default:**\
This matters because makers sometimes assume every visible string is directly editable. The common mistake is spending time hunting for a setting that is not exposed instead of validating the broader search flow.

### Search scope

This is the most important Search-specific concept for makers.

#### Sheet scope (`searchSheetIds`)

**What it does:**\
This optional setting narrows Search so it only queries specific databases. When it is empty, the runtime searches across all linked databases.

**How to use it:**\
The recommended setup is to leave `searchSheetIds` empty unless you have a strong, user-facing reason to restrict search. The current builder panel only shows a hint telling you that empty scope means all linked databases. The full multi-picker is not fully exposed there yet, but the runtime already honors `searchSheetIds` if it exists in the layout JSON.

**Why / recommended default:**\
The default should almost always be broad scope. Users usually interpret Search as “search the app,” not “search one carefully limited subset.” The common mistake is over-narrowing scope and then getting bug reports that Search cannot find records that do exist elsewhere.

{% hint style="warning" %}
**Scope guidance**\
Leave sheet scope empty unless there is a real boundary users understand, such as a role-specific app area or a compliance reason to exclude certain databases. Over-restricting Search makes the screen feel broken.
{% endhint %}

### Related setup outside chrome config

Search only feels complete when the maker also handles result destinations, navigation, publish flow, and user preview.

#### Result destination screens

**What it does:**\
Search results open the screen associated with the matching record. If that destination does not exist, the search experience feels incomplete even if the search query worked.

**How to use it:**\
Make sure each searchable database has an appropriate downstream screen, usually a details-style destination, so tapping a result leads somewhere useful.

**Why / recommended default:**\
Search is only as good as the record-opening path behind it. A common mistake is validating that results appear but forgetting to test where the user lands after tapping one.

#### Edit Navigation

**What it does:**\
This controls whether Search appears in the app’s main navigation and where users encounter it.

**How to use it:**\
Put Search somewhere users can reach without hunting for it. In many apps that means a primary tab or a near-top side-nav item, often close to Home.

**Why / recommended default:**\
Search is a utility screen, so discoverability matters. A common mistake is placing it too deep in navigation and then concluding users “do not use search,” when they may simply not find it.

#### Publish

**What it does:**\
Publishing makes the configured Search screen available in the live app.

**How to use it:**\
Publish after verifying the empty-state copy and after confirming the target destination screens are also live.

**Why / recommended default:**\
Search issues are easy to misdiagnose if one part of the navigation or result flow is unpublished. The common mistake is testing a new Search screen against an old published shell.

#### View as user

**What it does:**\
This lets you preview Search as a specific persona while testing visibility and result behavior.

**How to use it:**\
Use `View as user` when result visibility depends on role or private-app access. Search may be broad in concept, but the records a person can actually open can still differ by user.

**Why / recommended default:**\
Search can appear healthy for the maker while missing useful results for a real persona. The common mistake is validating only as the builder account and missing permission-based behavior.

## Recommended default setup

| Setting                 | Recommended value                                          |
| ----------------------- | ---------------------------------------------------------- |
| Empty state title       | Search your app                                            |
| Empty state description | Mention keyword search and, if relevant, scan-based lookup |
| Sheet scope             | Empty, so all linked databases are searchable              |
| Navigation              | A visible tab or side-nav item near Home                   |

## Testing checklist

* [ ] Search finds a known record from one database, proving the basic query path
* [ ] Search also finds a known record from a different database when scope is empty
* [ ] The empty state appears before typing, so the no-query experience is readable
* [ ] A nonsense query shows the `No matches` state, which proves the app is handling misses cleanly
* [ ] Tapping a result opens the correct downstream record screen
* [ ] Recent searches reappear after leaving and returning, because that local-memory behavior is part of the value
* [ ] `View as user` confirms role-specific result visibility where relevant

## Troubleshooting

| Symptom                                                    | Likely cause                                                              | What to check                                                  |
| ---------------------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------- |
| Search always returns no matches                           | Scope is too narrow or the query is weak                                  | Clear `searchSheetIds` and test with a known title value       |
| Search finds records in one database but not another       | Scope is restricted or the second sheet is not part of the searchable set | Recheck scope and linked database coverage                     |
| A result appears but opens the wrong place                 | The downstream screen mapping is not what you expected                    | Test which record screen is associated with that result        |
| Recent searches do not stick                               | Browser or device storage was cleared                                     | Remember recents are local to the device/browser               |
| Search feels broken to users even though some results work | Scope is too narrow for user expectations                                 | Reconsider whether broad app-wide search is the better default |

## Best practices

* Default to broad search unless you can explain the limit in user language.
* Keep Search near Home so users can shift from orientation to lookup quickly.
* Test the full flow from query to opened record, not just the result list.