From 8533b4046a262cf01d85b014a4e3ac6175575f14 Mon Sep 17 00:00:00 2001
From: Greg Brimble <gbrimble@cloudflare.com>
Date: Thu, 28 Aug 2025 13:28:55 -0400
Subject: [PATCH] Add keyboardShortcuts property to allow users to customize
 shortcuts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Address PR feedback: remove docs changes and update bundle size limits

- Remove documentation changes from api.mdx (not needed in v3 backport)
- Update bundlesize.config.json limits:
  - docsearch-react: 27 kB → 27.5 kB
  - docsearch-js: 35.5 kB → 36 kB

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 bundlesize.config.json                        |   4 +-
 packages/docsearch-react/src/DocSearch.tsx    |  17 +-
 .../docsearch-react/src/DocSearchButton.tsx   |  14 +-
 .../src/__tests__/keyboardShortcuts.test.tsx  | 152 ++++++++++++++++++
 .../src/constants/keyboardShortcuts.ts        |  24 +++
 .../src/types/KeyboardShortcuts.ts            |  14 ++
 packages/docsearch-react/src/types/index.ts   |   1 +
 .../src/useDocSearchKeyboardEvents.ts         |  17 +-
 8 files changed, 231 insertions(+), 12 deletions(-)
 create mode 100644 packages/docsearch-react/src/__tests__/keyboardShortcuts.test.tsx
 create mode 100644 packages/docsearch-react/src/constants/keyboardShortcuts.ts
 create mode 100644 packages/docsearch-react/src/types/KeyboardShortcuts.ts

diff --git a/bundlesize.config.json b/bundlesize.config.json
index 3d00a7813..ddf04030e 100644
--- a/bundlesize.config.json
+++ b/bundlesize.config.json
@@ -6,11 +6,11 @@
     },
     {
       "path": "packages/docsearch-react/dist/umd/index.js",
-      "maxSize": "27 kB"
+      "maxSize": "27.5 kB"
     },
     {
       "path": "packages/docsearch-js/dist/umd/index.js",
-      "maxSize": "35.5 kB"
+      "maxSize": "36 kB"
     }
   ]
 }
diff --git a/packages/docsearch-react/src/DocSearch.tsx b/packages/docsearch-react/src/DocSearch.tsx
index 54668a90c..cbbcd953b 100644
--- a/packages/docsearch-react/src/DocSearch.tsx
+++ b/packages/docsearch-react/src/DocSearch.tsx
@@ -5,7 +5,13 @@ import { createPortal } from 'react-dom';
 
 import { DocSearchButton } from './DocSearchButton';
 import { DocSearchModal } from './DocSearchModal';
-import type { DocSearchHit, DocSearchTheme, InternalDocSearchHit, StoredDocSearchHit } from './types';
+import type {
+  DocSearchHit,
+  DocSearchTheme,
+  InternalDocSearchHit,
+  KeyboardShortcuts,
+  StoredDocSearchHit,
+} from './types';
 import { useDocSearchKeyboardEvents } from './useDocSearchKeyboardEvents';
 import { useTheme } from './useTheme';
 
@@ -41,6 +47,7 @@ export interface DocSearchProps {
   translations?: DocSearchTranslations;
   getMissingResultsUrl?: ({ query }: { query: string }) => string;
   insights?: AutocompleteOptions<InternalDocSearchHit>['insights'];
+  keyboardShortcuts?: KeyboardShortcuts;
 }
 
 export function DocSearch({ ...props }: DocSearchProps): JSX.Element {
@@ -71,12 +78,18 @@ export function DocSearch({ ...props }: DocSearchProps): JSX.Element {
     onClose,
     onInput,
     searchButtonRef,
+    keyboardShortcuts: props.keyboardShortcuts,
   });
   useTheme({ theme: props.theme });
 
   return (
     <>
-      <DocSearchButton ref={searchButtonRef} translations={props?.translations?.button} onClick={onOpen} />
+      <DocSearchButton
+        ref={searchButtonRef}
+        translations={props?.translations?.button}
+        keyboardShortcuts={props.keyboardShortcuts}
+        onClick={onOpen}
+      />
 
       {isOpen &&
         createPortal(
diff --git a/packages/docsearch-react/src/DocSearchButton.tsx b/packages/docsearch-react/src/DocSearchButton.tsx
index 50db9aa2e..ece64dbcb 100644
--- a/packages/docsearch-react/src/DocSearchButton.tsx
+++ b/packages/docsearch-react/src/DocSearchButton.tsx
@@ -1,8 +1,9 @@
 import React, { useEffect, useState, type JSX } from 'react';
 
+import { getKeyboardShortcuts } from './constants/keyboardShortcuts';
 import { ControlKeyIcon } from './icons/ControlKeyIcon';
 import { SearchIcon } from './icons/SearchIcon';
-import type { DocSearchTheme } from './types';
+import type { DocSearchTheme, KeyboardShortcuts } from './types';
 import { useTheme } from './useTheme';
 
 export type ButtonTranslations = Partial<{
@@ -13,6 +14,7 @@ export type ButtonTranslations = Partial<{
 export type DocSearchButtonProps = React.ComponentProps<'button'> & {
   theme?: DocSearchTheme;
   translations?: ButtonTranslations;
+  keyboardShortcuts?: KeyboardShortcuts;
 };
 
 const ACTION_KEY_DEFAULT = 'Ctrl' as const;
@@ -23,8 +25,9 @@ function isAppleDevice(): boolean {
 }
 
 export const DocSearchButton = React.forwardRef<HTMLButtonElement, DocSearchButtonProps>(
-  ({ translations = {}, ...props }, ref) => {
+  ({ translations = {}, keyboardShortcuts, ...props }, ref) => {
     const { buttonText = 'Search', buttonAriaLabel = 'Search' } = translations;
+    const resolvedShortcuts = getKeyboardShortcuts(keyboardShortcuts);
 
     const [key, setKey] = useState<typeof ACTION_KEY_APPLE | typeof ACTION_KEY_DEFAULT | null>(null);
     useTheme({ theme: props.theme });
@@ -40,14 +43,15 @@ export const DocSearchButton = React.forwardRef<HTMLButtonElement, DocSearchButt
           ([ACTION_KEY_DEFAULT, 'Control', <ControlKeyIcon />] as const)
         : (['Meta', 'Meta', key] as const);
 
+    const isCtrlCmdKEnabled = resolvedShortcuts['Ctrl/Cmd+K'];
     const shortcut = `${actionKeyAltText}+k`;
 
     return (
       <button
         type="button"
         className="DocSearch DocSearch-Button"
-        aria-label={`${buttonAriaLabel} (${shortcut})`}
-        aria-keyshortcuts={shortcut}
+        aria-label={isCtrlCmdKEnabled ? `${buttonAriaLabel} (${shortcut})` : buttonAriaLabel}
+        aria-keyshortcuts={isCtrlCmdKEnabled ? shortcut : undefined}
         {...props}
         ref={ref}
       >
@@ -57,7 +61,7 @@ export const DocSearchButton = React.forwardRef<HTMLButtonElement, DocSearchButt
         </span>
 
         <span className="DocSearch-Button-Keys">
-          {key !== null && (
+          {key !== null && isCtrlCmdKEnabled && (
             <>
               <DocSearchButtonKey reactsToKey={actionKeyReactsTo}>{actionKeyChild}</DocSearchButtonKey>
               <DocSearchButtonKey reactsToKey="k">K</DocSearchButtonKey>
diff --git a/packages/docsearch-react/src/__tests__/keyboardShortcuts.test.tsx b/packages/docsearch-react/src/__tests__/keyboardShortcuts.test.tsx
new file mode 100644
index 000000000..929802c5b
--- /dev/null
+++ b/packages/docsearch-react/src/__tests__/keyboardShortcuts.test.tsx
@@ -0,0 +1,152 @@
+import { render, act, fireEvent, screen, cleanup } from '@testing-library/react';
+import React, { type JSX } from 'react';
+import { describe, it, expect, afterEach } from 'vitest';
+
+import '@testing-library/jest-dom/vitest';
+
+import { DocSearch as DocSearchComponent } from '../DocSearch';
+import type { DocSearchProps } from '../DocSearch';
+
+function DocSearch(props: Partial<DocSearchProps>): JSX.Element {
+  return <DocSearchComponent appId="woo" apiKey="foo" indexName="bar" {...props} />;
+}
+
+describe('keyboard shortcuts', () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  describe('default behavior', () => {
+    it('shows Ctrl/Cmd+K shortcut hint by default', () => {
+      render(<DocSearch />);
+
+      const button = document.querySelector('.DocSearch-Button');
+      expect(button).toBeInTheDocument();
+      expect(button?.getAttribute('aria-label')).toMatch(/\(Control\+k\)/);
+      expect(document.querySelector('.DocSearch-Button-Keys')).toBeInTheDocument();
+    });
+
+    it('responds to Ctrl+K keyboard shortcut by default', () => {
+      render(<DocSearch />);
+
+      expect(document.querySelector('.DocSearch-Modal')).not.toBeInTheDocument();
+
+      act(() => {
+        fireEvent.keyDown(document, { key: 'k', ctrlKey: true });
+      });
+
+      expect(document.querySelector('.DocSearch-Modal')).toBeInTheDocument();
+    });
+
+    it('responds to / keyboard shortcut by default', () => {
+      render(<DocSearch />);
+
+      expect(document.querySelector('.DocSearch-Modal')).not.toBeInTheDocument();
+
+      act(() => {
+        fireEvent.keyDown(document, { key: '/' });
+      });
+
+      expect(document.querySelector('.DocSearch-Modal')).toBeInTheDocument();
+    });
+  });
+
+  describe('custom keyboard shortcuts configuration', () => {
+    it('hides shortcut hint when Ctrl/Cmd+K is disabled', () => {
+      render(<DocSearch keyboardShortcuts={{ 'Ctrl/Cmd+K': false }} />);
+
+      const button = document.querySelector('.DocSearch-Button');
+      expect(button).toBeInTheDocument();
+      expect(button?.getAttribute('aria-label')).toBe('Search');
+      expect(document.querySelector('.DocSearch-Button-Keys')).toBeInTheDocument();
+      expect(document.querySelector('.DocSearch-Button-Key')).not.toBeInTheDocument();
+    });
+
+    it('does not respond to Ctrl+K when disabled', () => {
+      render(<DocSearch keyboardShortcuts={{ 'Ctrl/Cmd+K': false }} />);
+
+      expect(document.querySelector('.DocSearch-Modal')).not.toBeInTheDocument();
+
+      act(() => {
+        fireEvent.keyDown(document, { key: 'k', ctrlKey: true });
+      });
+
+      expect(document.querySelector('.DocSearch-Modal')).not.toBeInTheDocument();
+    });
+
+    it('does not respond to / when disabled', () => {
+      render(<DocSearch keyboardShortcuts={{ '/': false }} />);
+
+      expect(document.querySelector('.DocSearch-Modal')).not.toBeInTheDocument();
+
+      act(() => {
+        fireEvent.keyDown(document, { key: '/' });
+      });
+
+      expect(document.querySelector('.DocSearch-Modal')).not.toBeInTheDocument();
+    });
+
+    it('still shows shortcut hint when only / is disabled', () => {
+      render(<DocSearch keyboardShortcuts={{ '/': false }} />);
+
+      const button = document.querySelector('.DocSearch-Button');
+      expect(button).toBeInTheDocument();
+      expect(button?.getAttribute('aria-label')).toMatch(/\(Control\+k\)/);
+      expect(document.querySelector('.DocSearch-Button-Key')).toBeInTheDocument();
+    });
+
+    it('responds to enabled shortcuts when others are disabled', () => {
+      render(<DocSearch keyboardShortcuts={{ '/': false }} />);
+
+      expect(document.querySelector('.DocSearch-Modal')).not.toBeInTheDocument();
+
+      act(() => {
+        fireEvent.keyDown(document, { key: 'k', ctrlKey: true });
+      });
+
+      expect(document.querySelector('.DocSearch-Modal')).toBeInTheDocument();
+    });
+
+    it('can disable all shortcuts', () => {
+      render(<DocSearch keyboardShortcuts={{ 'Ctrl/Cmd+K': false, '/': false }} />);
+
+      const button = document.querySelector('.DocSearch-Button');
+      expect(button?.getAttribute('aria-label')).toBe('Search');
+      expect(document.querySelector('.DocSearch-Button-Key')).not.toBeInTheDocument();
+
+      expect(document.querySelector('.DocSearch-Modal')).not.toBeInTheDocument();
+
+      act(() => {
+        fireEvent.keyDown(document, { key: 'k', ctrlKey: true });
+      });
+
+      expect(document.querySelector('.DocSearch-Modal')).not.toBeInTheDocument();
+
+      act(() => {
+        fireEvent.keyDown(document, { key: '/' });
+      });
+
+      expect(document.querySelector('.DocSearch-Modal')).not.toBeInTheDocument();
+    });
+  });
+
+  describe('Escape key behavior', () => {
+    it('always responds to Escape to close modal regardless of configuration', async () => {
+      render(<DocSearch keyboardShortcuts={{ 'Ctrl/Cmd+K': false, '/': false }} />);
+
+      // Open modal via button click
+      await act(async () => {
+        fireEvent.click(await screen.findByText('Search'));
+      });
+
+      expect(document.querySelector('.DocSearch-Modal')).toBeInTheDocument();
+
+      // Close with Escape
+      act(() => {
+        fireEvent.keyDown(document, { code: 'Escape' });
+      });
+
+      expect(document.querySelector('.DocSearch-Modal')).not.toBeInTheDocument();
+    });
+  });
+});
diff --git a/packages/docsearch-react/src/constants/keyboardShortcuts.ts b/packages/docsearch-react/src/constants/keyboardShortcuts.ts
new file mode 100644
index 000000000..5a343aa9e
--- /dev/null
+++ b/packages/docsearch-react/src/constants/keyboardShortcuts.ts
@@ -0,0 +1,24 @@
+import type { KeyboardShortcuts } from '../types';
+
+/**
+ * Default keyboard shortcuts configuration for DocSearch.
+ * These values are used when no keyboardShortcuts prop is provided
+ * or when specific shortcuts are not configured.
+ */
+export const DEFAULT_KEYBOARD_SHORTCUTS: Required<KeyboardShortcuts> = {
+  'Ctrl/Cmd+K': true,
+  '/': true,
+} as const;
+
+/**
+ * Merges user-provided keyboard shortcuts with defaults.
+ *
+ * @param userShortcuts - Optional user configuration.
+ * @returns Complete keyboard shortcuts configuration with defaults applied.
+ */
+export function getKeyboardShortcuts(userShortcuts?: KeyboardShortcuts): Required<KeyboardShortcuts> {
+  return {
+    ...DEFAULT_KEYBOARD_SHORTCUTS,
+    ...userShortcuts,
+  };
+}
diff --git a/packages/docsearch-react/src/types/KeyboardShortcuts.ts b/packages/docsearch-react/src/types/KeyboardShortcuts.ts
new file mode 100644
index 000000000..3a37122a6
--- /dev/null
+++ b/packages/docsearch-react/src/types/KeyboardShortcuts.ts
@@ -0,0 +1,14 @@
+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;
+}
diff --git a/packages/docsearch-react/src/types/index.ts b/packages/docsearch-react/src/types/index.ts
index 2922cbc29..a50d953e6 100644
--- a/packages/docsearch-react/src/types/index.ts
+++ b/packages/docsearch-react/src/types/index.ts
@@ -2,4 +2,5 @@ export * from './DocSearchHit';
 export * from './DocSearchState';
 export * from './DocSearchTheme';
 export * from './InternalDocSearchHit';
+export * from './KeyboardShortcuts';
 export * from './StoredDocSearchHit';
diff --git a/packages/docsearch-react/src/useDocSearchKeyboardEvents.ts b/packages/docsearch-react/src/useDocSearchKeyboardEvents.ts
index 6ca994918..3a00607a3 100644
--- a/packages/docsearch-react/src/useDocSearchKeyboardEvents.ts
+++ b/packages/docsearch-react/src/useDocSearchKeyboardEvents.ts
@@ -1,11 +1,15 @@
 import React from 'react';
 
+import { getKeyboardShortcuts } from './constants/keyboardShortcuts';
+import type { KeyboardShortcuts } from './types';
+
 export interface UseDocSearchKeyboardEventsProps {
   isOpen: boolean;
   onOpen: () => void;
   onClose: () => void;
   onInput?: (event: KeyboardEvent) => void;
   searchButtonRef: React.RefObject<HTMLButtonElement | null>;
+  keyboardShortcuts?: KeyboardShortcuts;
 }
 
 function isEditingContent(event: KeyboardEvent): boolean {
@@ -21,19 +25,26 @@ export function useDocSearchKeyboardEvents({
   onClose,
   onInput,
   searchButtonRef,
+  keyboardShortcuts,
 }: UseDocSearchKeyboardEventsProps): void {
+  const resolvedShortcuts = getKeyboardShortcuts(keyboardShortcuts);
+
   React.useEffect(() => {
     function onKeyDown(event: KeyboardEvent): void {
+      const isCmdK =
+        resolvedShortcuts['Ctrl/Cmd+K'] && event.key?.toLowerCase() === 'k' && (event.metaKey || event.ctrlKey);
+      const isSlash = resolvedShortcuts['/'] && event.key === '/';
+
       if (
         (event.code === 'Escape' && isOpen) ||
         // The `Cmd+K` shortcut both opens and closes the modal.
         // We need to check for `event.key` because it can be `undefined` with
         // Chrome's autofill feature.
         // See https://github.com/paperjs/paper.js/issues/1398
-        (event.key?.toLowerCase() === 'k' && (event.metaKey || event.ctrlKey)) ||
+        isCmdK ||
         // The `/` shortcut opens but doesn't close the modal because it's
         // a character.
-        (!isEditingContent(event) && event.key === '/' && !isOpen)
+        (!isEditingContent(event) && isSlash && !isOpen)
       ) {
         event.preventDefault();
 
@@ -60,5 +71,5 @@ export function useDocSearchKeyboardEvents({
     return (): void => {
       window.removeEventListener('keydown', onKeyDown);
     };
-  }, [isOpen, onOpen, onClose, onInput, searchButtonRef]);
+  }, [isOpen, onOpen, onClose, onInput, searchButtonRef, resolvedShortcuts]);
 }