Skip to main content
`Ctrl`+`K`

# Search bar / search button

On narrow viewports, users can access search by clicking the magnifying glass icon () in the Header / Navigation Bar. On wide viewports, the magnifying glass icon, search input field, and keyboard shortcut for focusing the search input field are all shown. The keyboard shortcut is:

- `Ctrl` + `K` (Linux, Windows)

- `⌘` + `K` (macOS)

You can also configure some aspects of the search button and search field, described below.

## Configure the search field position

The position of the search button is controlled by `search-button` and by default is included in `html_theme_options["navbar_persistent"]`; you may move it elsewhere as befits your site’s layout, or remove it. You can also add an always-visible search field to some/all pages in your site by adding `search-field.html` to one of the configuration variables (e.g., `html_sidebars`, `html_theme_options["footer_start"]`, etc.).

For example, if you’d like the search field to be in your sidebar, add it to the sidebar templates like so:

    html_sidebars = {
        "**": ["search-field.html", "sidebar-nav-bs.html", "sidebar-ethical-ads.html"]
    }

If instead, you’d like to put the search field in the top navbar, use the following configuration:

    html_theme_options = {
        "navbar_end": ["navbar-icon-links.html", "search-field.html"]
    }

Warning

If a page includes both the search button and an always-visible search field, the keyboard shortcuts will focus on the always-visible field and the hidden search field overlay will not display. This may not be what you want: on small screens (i.e. mobile devices) the sidebars may be hidden in a drawer, and if the persistent search field is there, it may receive focus without actually being made visible. It is strongly recommended that you use either the search button and the hidden/overlaid field that comes with it, or use a persistent search field in a place that makes sense for your layout.

## Configure the search bar text

To modify the text that is in the search bar before people click on it, add the following configuration to your `conf.py` file:

    html_theme_options = {
        "search_bar_text": "Your text here..."
    }

## Configure the inline search results (search-as-you-type) feature

Set the `search_as_you_type` HTML theme option to `True`.

    html_theme_options = {
        "search_as_you_type": True
    }

## Disable the built-in search

If your site uses a third-party search backend (e.g. the Read the Docs server-side search addon), you may want to disable the built-in pydata search entirely. Set the `disable_search` HTML theme option to `True`:

    html_theme_options = {
        "disable_search": True
    }

This does two things automatically:

- The `#pst-search-dialog` overlay is omitted from the page, so the built-in search dialog never appears and keyboard shortcuts (`Ctrl` + `K` / `⌘` + `K`) do not open it.

- `navbar_persistent` is set to an empty list, so the default search button is no longer rendered in the navbar.

Note

`disable_search` only controls `search-button-field` (the full navbar button showing the search label and keyboard shortcut) via `navbar_persistent`. It does not remove `search-button` (the icon-only variant) or `search-field.html` if you have placed either of those explicitly elsewhere in your layout. Remove them manually if needed.

If you set `navbar_persistent` explicitly in your `html_theme_options`, that value takes precedence and `disable_search` will not modify it.