> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.com/algolia/docsearch/llms.txt > Use this file to discover all available pages before exploring further. # Keyboard Shortcuts > Configure and customize keyboard shortcuts for DocSearch 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: Opens and closes the search modal. This is the most common shortcut pattern used across documentation sites. Opens the search modal. This shortcut only opens the modal (doesn't close it) and is ignored when typing in input fields. Closes the search modal. This cannot be disabled and is always available. ## Configuration Configure keyboard shortcuts using the `keyboardShortcuts` prop: ```jsx theme={null} import { DocSearch } from '@docsearch/react'; function App() { return ( ); } ``` ### Disabling Shortcuts You can disable specific shortcuts by setting them to `false`: ```jsx Disable Cmd+K theme={null} ``` ```jsx Disable Forward Slash theme={null} ``` ```jsx Disable All Shortcuts theme={null} ``` 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): ```typescript theme={null} 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 ``, `

`, `<select>`, or `contentEditable` elements
* **Character-based**: Since `/` is a typeable character, it only opens the modal (doesn't toggle)

```typescript theme={null}
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:

<Steps>
  <Step title="User opens search">
    Press `Cmd+K` or `/`
  </Step>

<Step title="User activates Ask AI">
    Click the Ask AI button or suggested question
  </Step>

<Step title="First Escape">
    Returns to regular search mode
  </Step>

<Step title="Second Escape">
    Closes the search modal
  </Step>
</Steps>

## Usage Examples

### Only Allow Cmd+K

If you want to prevent the `/` shortcut (perhaps it conflicts with your site's routing):

```jsx theme={null}
<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:

```jsx theme={null}
<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:

```jsx theme={null}
<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_API_KEY"
  indexName="YOUR_INDEX_NAME"
  keyboardShortcuts={{
    'Ctrl/Cmd+K': false,
    '/': false,
  }}
/>
```

<Tip>
  Even with all shortcuts disabled, users can still close the modal with the Escape key or by clicking outside the modal.
</Tip>

## Implementation Details

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

### Event Listener Setup

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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

<Steps>
  <Step title="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.
  </Step>

<Step title="Communicate changes">
    If you disable or change the default shortcuts, make sure to update your documentation and any keyboard shortcut hints in your UI.
  </Step>

<Step title="Test across platforms">
    Remember that `Cmd+K` becomes `Ctrl+K` on Windows/Linux. Test your configuration on different operating systems.
  </Step>

<Step title="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.
  </Step>
</Steps>