DocSearchButton

The DocSearchButton component renders the search button that triggers the DocSearch modal. It’s rendered automatically by the DocSearch component but can also be used standalone for custom implementations.

Import

import { DocSearchButton } from '@docsearch/react';

Usage

import { DocSearchButton } from '@docsearch/react';

function SearchTrigger() {
  return (
    <DocSearchButton
      onClick={() => {
        // Open your custom search modal
      }}
    />
  );
}

Props

The DocSearchButton component extends native HTML button props and accepts all standard button attributes (className, onClick, etc.).

theme

'light' | 'dark'

Theme applied to the button styling.

translations

ButtonTranslations

Localized strings for the button text and aria labels.Object with optional properties:

buttonText (string, default: “Search”): Button text displayed in the button
buttonAriaLabel (string, default: “Search”): Aria label for accessibility

keyboardShortcuts

DocSearchModalShortcuts

Configuration for keyboard shortcuts display.Object with optional properties:

'Ctrl/Cmd+K' (boolean): Whether to show the Ctrl/Cmd+K keyboard shortcut hint

When enabled, the button will display the appropriate keyboard shortcut (⌘K on Mac, Ctrl+K on Windows/Linux) and update the aria-label accordingly.

...buttonProps

React.ComponentProps<'button'>

All standard HTML button attributes are supported, including:

onClick: Click event handler
className: CSS class name
style: Inline styles
disabled: Disabled state
type: Button type
And all other native button attributes

Button Structure

The button renders with the following structure:

<button type="button" class="DocSearch DocSearch-Button" aria-label="Search (Ctrl+k)">
  <span class="DocSearch-Button-Container">
    <!-- Search Icon -->
    <span class="DocSearch-Button-Placeholder">Search</span>
  </span>
  <span class="DocSearch-Button-Keys">
    <kbd class="DocSearch-Button-Key">Ctrl</kbd>
    <kbd class="DocSearch-Button-Key">K</kbd>
  </span>
</button>

Keyboard Shortcut Display

The button automatically detects the user’s operating system and displays the appropriate keyboard shortcut:

macOS: Shows ⌘K
Windows/Linux: Shows Ctrl+K

The keyboard shortcut keys are interactive and respond to actual key presses - they visually depress when the user presses the corresponding keys.

Ref

The component supports React.forwardRef and forwards the ref to the underlying button element:

import { useRef } from 'react';
import { DocSearchButton } from '@docsearch/react';

function SearchTrigger() {
  const buttonRef = useRef(null);

  return (
    <DocSearchButton
      ref={buttonRef}
      onClick={() => {
        // Button element is accessible via buttonRef.current
      }}
    />
  );
}

Styling

The button uses BEM-style CSS classes for styling:

DocSearch: Base DocSearch namespace
DocSearch-Button: Main button class
DocSearch-Button-Container: Container for icon and text
DocSearch-Button-Placeholder: Text placeholder
DocSearch-Button-Keys: Container for keyboard shortcut
DocSearch-Button-Key: Individual key in the shortcut
DocSearch-Button-Key--pressed: Applied when key is pressed
DocSearch-Button-Key--ctrl: Specific styling for Ctrl key

Types

ButtonTranslations

type ButtonTranslations = Partial<{
  buttonText: string;
  buttonAriaLabel: string;
}>;