Skip to main content

Customize the search bar

This page is about labels and behavior (what the button says, the shortcut, empty copy). For colors and radius, see Style the search UI. That guide includes a visual worked example.

Worked example on this site​

This documentation site uses the config below. Look at the navbar: the trigger says Search docs, the shortcut hint is ⌘K / Ctrl+K, and the modal placeholder is Find guides, APIs, how-tos….

ControlDefaultThis site
Trigger labelSearchSearch docs
PlaceholderSearch docs…Find guides, APIs, how-tos…
Empty resultsNo resultsNothing matched. Try another phrase
Debounce120 ms100 ms
Default pages88
tip

Open ⌘K now and compare the labels to the table. That is the customization working, not a separate demo component.

Copy this config​

docusaurus.config.ts
plugins: [
[
'docusaurus-plugin-docsense',
{
docsDirs: ['docs'],
docsRouteBasePath: '/docs',
resultLimit: 8,
searchBar: {
placeholder: 'Find guides, APIs, how-tos…',
triggerLabel: 'Search docs',
shortcut: 'mod+k',
showShortcutHint: true,
modalAriaLabel: 'Search docs',
emptyResultsLabel: 'Nothing matched. Try another phrase',
debounceMs: 100,
},
},
],
],

Optional overrides under themeConfig.docsense (also used on this site):

themeConfig: {
docsense: {
resultLimit: 8,
searchBar: {
placeholder: 'Find guides, APIs, how-tos…',
triggerLabel: 'Search docs',
},
},
},

What each field does​

FieldDefaultPurpose
placeholderSearch docs…Text inside the modal input
triggerLabelSearchNavbar button label
shortcutmod+kKeyboard shortcut (mod is ⌘ on macOS and Ctrl elsewhere)
showShortcutHinttrueShow the shortcut key on the trigger
modalAriaLabelSearch docsAccessible name for the modal
emptyResultsLabelNo resultsCopy when a query has no hits
debounceMs120Wait time before running a query while typing

Change the default page count​

resultLimit sets the starting number of pages in the modal (default 8). Readers can still change it with Pages − / +. The UI clamps that control between 3 and 20, and disables − or + at those edges so the count cannot go below 3 or above 20.

{
resultLimit: 10,
}

Point at different docs folders​

{
docsDirs: ['docs', 'guides'],
docsRouteBasePath: '/docs',
}

docsRouteBasePath must match how Docusaurus serves those pages so result links resolve correctly.

Next steps​