Skip to main content
DocSearch provides built-in keyboard shortcuts to enhance the search experience. You can enable, disable, or customize these shortcuts to match your site’s needs.

​
Default Shortcuts

DocSearch comes with two default keyboard shortcuts:
1

Cmd+K / Ctrl+K

Opens and closes the search modal. This is the most common shortcut pattern used across documentation sites.
2

/ (Forward Slash)

Opens the search modal. This shortcut only opens the modal (doesn’t close it) and is ignored when typing in input fields.
3

Escape

Closes the search modal. This cannot be disabled and is always available.

​
Configuration

Configure keyboard shortcuts using the keyboardShortcuts prop: 
import { DocSearch } from '@docsearch/react';

function App() {
  return (
    <DocSearch
      appId="YOUR_APP_ID"
      apiKey="YOUR_API_KEY"
      indexName="YOUR_INDEX_NAME"
      keyboardShortcuts={{
        'Ctrl/Cmd+K': true,
        '/': true,
      }}
    />
  );
}

​
Disabling Shortcuts

You can disable specific shortcuts by setting them to false: 
<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_API_KEY"
  indexName="YOUR_INDEX_NAME"
  keyboardShortcuts={{
    'Ctrl/Cmd+K': false,
    '/': true,
  }}
/>
Even when all shortcuts are disabled, the Escape key will still close the modal. This ensures users always have a way to dismiss the search interface.

​
How Shortcuts Work

​
Cmd+K / Ctrl+K

The Ctrl/Cmd+K shortcut automatically detects the user’s operating system:
  • macOS: Triggers on Cmd+K (⌘ K)
  • Windows/Linux: Triggers on Ctrl+K
This shortcut toggles the modal - it both opens and closes it. The implementation checks for the metaKey (Cmd on Mac) or ctrlKey (Ctrl on Windows/Linux): 
const isCmdK = event.key?.toLowerCase() === 'k' && 
               (event.metaKey || event.ctrlKey);

​
Forward Slash (/)

The forward slash shortcut only opens the modal and does not close it. It’s designed to be non-intrusive:
  • Ignored in input fields: The shortcut won’t trigger when typing in <input>, <textarea>, <select>, or contentEditable elements
  • Character-based: Since / is a typeable character, it only opens the modal (doesn’t toggle)
function isEditingContent(event: KeyboardEvent): boolean {
  const element = event.composedPath()[0] as HTMLElement;
  const tagName = element.tagName;
  
  return element.isContentEditable || 
         tagName === 'INPUT' || 
         tagName === 'SELECT' || 
         tagName === 'TEXTAREA';
}

​
Ask AI Integration

When using the Ask AI feature, there’s an additional behavior:
  • Escape in Ask AI mode: If the search modal is open with Ask AI active, pressing Escape first exits Ask AI mode and returns to regular search
  • Second Escape press: Closes the modal entirely
This provides a natural navigation hierarchy:
1

User opens search

Press Cmd+K or /
2

User activates Ask AI

Click the Ask AI button or suggested question
3

First Escape

Returns to regular search mode
4

Second Escape

Closes the search modal

​
Usage Examples

​
Only Allow Cmd+K

If you want to prevent the / shortcut (perhaps it conflicts with your site’s routing): 
<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_API_KEY"
  indexName="YOUR_INDEX_NAME"
  keyboardShortcuts={{
    'Ctrl/Cmd+K': true,
    '/': false,
  }}
/>

​
Only Allow Forward Slash

If you want to reserve Cmd+K for another feature: 
<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_API_KEY"
  indexName="YOUR_INDEX_NAME"
  keyboardShortcuts={{
    'Ctrl/Cmd+K': false,
    '/': true,
  }}
/>

​
Button-Only Activation

Disable all keyboard shortcuts to only allow opening via the search button: 
<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_API_KEY"
  indexName="YOUR_INDEX_NAME"
  keyboardShortcuts={{
    'Ctrl/Cmd+K': false,
    '/': false,
  }}
/>
Even with all shortcuts disabled, users can still close the modal with the Escape key or by clicking outside the modal.

​
Implementation Details

The keyboard shortcuts system is implemented using a custom React hook called useDocSearchKeyboardEvents. Here’s how it works:

​
Event Listener Setup

React.useEffect(() => {
  function onKeyDown(event: KeyboardEvent): void {
    // Check for Escape in Ask AI mode
    if (isOpen && event.code === 'Escape' && isAskAiActive) {
      onAskAiToggle(false);
      return;
    }

    const isCmdK = 
      resolvedShortcuts['Ctrl/Cmd+K'] && 
      event.key?.toLowerCase() === 'k' && 
      (event.metaKey || event.ctrlKey);
      
    const isSlash = 
      resolvedShortcuts['/'] && 
      event.key === '/';

    if (
      (event.code === 'Escape' && isOpen) ||
      isCmdK ||
      (!isEditingContent(event) && isSlash && !isOpen)
    ) {
      event.preventDefault();
      
      if (isOpen) {
        onClose();
      } else if (!document.body.classList.contains('DocSearch--active')) {
        onOpen();
      }
    }
  }

  window.addEventListener('keydown', onKeyDown);
  return () => window.removeEventListener('keydown', onKeyDown);
}, [isOpen, onOpen, onClose, isAskAiActive, onAskAiToggle, resolvedShortcuts]);

​
Default Configuration

The default keyboard shortcuts are defined in constants: 
export const DEFAULT_KEYBOARD_SHORTCUTS = {
  'Ctrl/Cmd+K': true,
  '/': true,
} as const;

export function getKeyboardShortcuts(userShortcuts) {
  return {
    ...DEFAULT_KEYBOARD_SHORTCUTS,
    ...userShortcuts,
  };
}

​
TypeScript Interface

The keyboard shortcuts configuration uses the following TypeScript interface: 
export interface KeyboardShortcuts {
  /**
   * Enable/disable the Ctrl/Cmd+K shortcut to toggle the search modal.
   *
   * @default true
   */
  'Ctrl/Cmd+K'?: boolean;
  
  /**
   * Enable/disable the / shortcut to open the search modal.
   *
   * @default true
   */
  '/'?: boolean;
}

​
Best Practices

1

Keep defaults when possible

The default shortcuts (Cmd+K and /) are familiar to most users from other documentation sites. Only disable them if they conflict with existing functionality.
2

Communicate changes

If you disable or change the default shortcuts, make sure to update your documentation and any keyboard shortcut hints in your UI.
3

Test across platforms

Remember that Cmd+K becomes Ctrl+K on Windows/Linux. Test your configuration on different operating systems.
4

Consider accessibility

Keyboard shortcuts are essential for accessibility. Even if you disable default shortcuts, ensure there’s always a keyboard-accessible way to open search.

Build docs developers (and LLMs) love

Get started for freeTalk to us