feat(v3): allow overriding default toggle key

packages/docsearch-react/src/DocSearch.tsx

@@ -41,6 +41,7 @@ export interface DocSearchProps {
   initialQuery?: string;
   navigator?: AutocompleteOptions<InternalDocSearchHit>['navigator'];
   translations?: DocSearchTranslations;
+  toggleKey?: string;
 }
 
 export function DocSearch(props: DocSearchProps) {
@@ -49,6 +50,7 @@ export function DocSearch(props: DocSearchProps) {
   const [initialQuery, setInitialQuery] = React.useState<string | undefined>(
     props?.initialQuery || undefined
   );
+  const toggleKey = props?.toggleKey || 'k';
 
   const onOpen = React.useCallback(() => {
     setIsOpen(true);
@@ -72,13 +74,15 @@ export function DocSearch(props: DocSearchProps) {
     onClose,
     onInput,
     searchButtonRef,
+    toggleKey,
   });
 
   return (
     <>
       <DocSearchButton
         ref={searchButtonRef}
         translations={props?.translations?.button}
+        toggleKey={toggleKey}
         onClick={onOpen}
       />
 

packages/docsearch-react/src/DocSearchButton.tsx

@@ -10,6 +10,7 @@ export type ButtonTranslations = Partial<{
 
 export type DocSearchButtonProps = React.ComponentProps<'button'> & {
   translations?: ButtonTranslations;
+  toggleKey?: string;
 };
 
 const ACTION_KEY_DEFAULT = 'Ctrl' as const;
@@ -22,7 +23,7 @@ function isAppleDevice() {
 export const DocSearchButton = React.forwardRef<
   HTMLButtonElement,
   DocSearchButtonProps
->(({ translations = {}, ...props }, ref) => {
+>(({ translations = {}, toggleKey = 'k', ...props }, ref) => {
   const { buttonText = 'Search', buttonAriaLabel = 'Search' } = translations;
 
   const key = useMemo<
@@ -53,7 +54,9 @@ export const DocSearchButton = React.forwardRef<
             <span className="DocSearch-Button-Key">
               {key === ACTION_KEY_DEFAULT ? <ControlKeyIcon /> : key}
             </span>
-            <span className="DocSearch-Button-Key">K</span>
+            <span className="DocSearch-Button-Key">
+              {toggleKey.toLocaleUpperCase()}
+            </span>
           </>
         )}
       </span>

packages/docsearch-react/src/__tests__/api.test.tsx

@@ -5,6 +5,7 @@ import {
   screen,
   act,
 } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import React from 'react';
 
 import '@testing-library/jest-dom';
@@ -27,6 +28,44 @@ describe('api', () => {
     expect(document.querySelector('.DocSearch')).toBeInTheDocument();
   });
 
+  describe('toggleKey', () => {
+    it('opens and close the modal with the default shortcut', async () => {
+      render(<DocSearch />);
+
+      await waitFor(() => {
+        userEvent.keyboard('{meta}{k}');
+      });
+
+      expect(document.querySelector('.DocSearch-Modal')).toBeInTheDocument();
+
+      await waitFor(() => {
+        userEvent.keyboard('{meta}{k}');
+      });
+
+      expect(
+        document.querySelector('.DocSearch-Modal')
+      ).not.toBeInTheDocument();
+    });
+
+    it('overrides the default shortcut', async () => {
+      render(<DocSearch toggleKey="u" />);
+
+      await waitFor(() => {
+        userEvent.keyboard('{meta}{u}');
+      });
+
+      expect(document.querySelector('.DocSearch-Modal')).toBeInTheDocument();
+
+      await waitFor(() => {
+        userEvent.keyboard('{meta}{u}');
+      });
+
+      expect(
+        document.querySelector('.DocSearch-Modal')
+      ).not.toBeInTheDocument();
+    });
+  });
+
   describe('translations', () => {
     it('overrides the default DocSearchButton text', () => {
       render(

packages/docsearch-react/src/useDocSearchKeyboardEvents.ts

@@ -6,6 +6,7 @@ export interface UseDocSearchKeyboardEventsProps {
   onClose: () => void;
   onInput?: (event: KeyboardEvent) => void;
   searchButtonRef?: React.RefObject<HTMLButtonElement>;
+  toggleKey: string;
 }
 
 function isEditingContent(event: KeyboardEvent): boolean {
@@ -26,6 +27,7 @@ export function useDocSearchKeyboardEvents({
   onClose,
   onInput,
   searchButtonRef,
+  toggleKey = 'k',
 }: UseDocSearchKeyboardEventsProps) {
   React.useEffect(() => {
     function onKeyDown(event: KeyboardEvent) {
@@ -37,9 +39,9 @@ export function useDocSearchKeyboardEvents({
         }
       }
       if (
-        (event.keyCode === 27 && isOpen) ||
-        // The `Cmd+K` shortcut both opens and closes the modal.
-        (event.key === 'k' && (event.metaKey || event.ctrlKey)) ||
+        (event.key === 'Escape' && isOpen) ||
+        // The `Cmd+toggleKey` shortcut both opens and closes the modal.
+        (event.key === toggleKey && (event.metaKey || event.ctrlKey)) ||
         // The `/` shortcut opens but doesn't close the modal because it's
         // a character.
         (!isEditingContent(event) && event.key === '/' && !isOpen)
@@ -69,5 +71,5 @@ export function useDocSearchKeyboardEvents({
     return () => {
       window.removeEventListener('keydown', onKeyDown);
     };
-  }, [isOpen, onOpen, onClose, onInput, searchButtonRef]);
+  }, [isOpen, onOpen, onClose, onInput, searchButtonRef, toggleKey]);
 }

packages/website/docs/api.mdx

@@ -169,6 +169,11 @@ const translations: DocSearchTranslations = {
 
 </div>
 </details>
+## `toggleKey`
+
+> `type: string` | `default: "k"` | **optional**
+
+Allow overriding the default key to open/close the DocSearch modal.
 
 </TabItem>
 
@@ -309,6 +314,12 @@ const translations: DocSearchTranslations = {
 </div>
 </details>
 
+## `toggleKey`
+
+> `type: string` | `default: "k"` | **optional**
+
+Allow overriding the default key to open/close the DocSearch modal.
+
 </TabItem>
 
 </Tabs>