diff --git a/docs/Search.md b/docs/Search.md index e3932ac8f2c..988cbfba116 100644 --- a/docs/Search.md +++ b/docs/Search.md @@ -166,15 +166,17 @@ export const App = () => ( The `` component accepts the following props: -| Prop | Required | Type | Default | Description | -| -------------- | -------- | --------------------------------------------------------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------- | -| `children` | Optional | `Element` | `` | A component that will display the results. | -| `disableHighlight` | Optional | `boolean` | `false` | Disable the highlight of the search term of each result. | -| `historySize` | Optional | `number` | 5 | The number of past queries to keep in history. | -| `isInAppBar` | Optional | `boolean` | `true` | Apply a dedicated style to the `` if true | -| `options` | Optional | `Object` | - | An object containing options to apply to the search. | -| `queryOptions` | Optional | [`UseQuery Options`](https://tanstack.com/query/v3/docs/react/reference/useQuery) | - | `react-query` options for the search query | -| `wait` | Optional | `number` | 500 | The delay of debounce for the search to launch after typing in ms. | +| Prop | Required | Type | Default | Description | +| ---------------------- | -------- | --------------------------------------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------- | +| `children` | Optional | `Element` | `` | A component that will display the results. | +| `disableHighlight` | Optional | `boolean` | `false` | Disable the highlight of the search term of each result. | +| `historySize` | Optional | `number` | 5 | The number of past queries to keep in history. | +| `keyboard ShortcutIcon`| Optional | `boolean` or `ReactElement` | `Ctrl+k` or `⌘+k` | Disable or configure the keyboard shortcut icon. | +| `isInAppBar` | Optional | `boolean` | `true` | Apply a dedicated style to the `` if true | +| `options` | Optional | `Object` | - | An object containing options to apply to the search. | +| `queryOptions` | Optional | [`UseQuery Options`](https://tanstack.com/query/v3/docs/react/reference/useQuery) | - | `react-query` options for the search query | +| `wait` | Optional | `number` | 500 | The delay of debounce for the search to launch after typing in ms. | +| `withKeyboard Shortcut`| Optional | `boolean` or [`Keys`](https://react-hotkeys-hook.vercel.app/) | `false` | Enable or configure a shortcut to open and access the search input and their results. | Additional props are passed down to the Material UI [``](https://mui.com/material-ui/react-text-field/) component. @@ -238,6 +240,30 @@ The number of previous user searches to keep in the popover. For example, if a u ``` +## `keyboardShortcutIcon` + +Use the `keyboardShortcutIcon` prop to disable or customize the keyboard shortcut icon. + +![Keyboard Shortcut Icon](./img/ra-search-keyboard-shortcut-icon.png) + +```tsx +Shift+s} /> +``` + +If you don't want to display this icon, you can pass `false` to the `keyboardShortcutIcon` prop: + +```tsx + +``` + +## `isInAppBar` + +The `` component has a specific style to fit the admin appBar. If you need to render the `` component elsewhere, you can set `isInAppBar` to `false` and hence apply the default MUI style. + +```tsx + +``` + ## `options` An object containing options to apply to the search: @@ -271,6 +297,53 @@ The number of milliseconds to wait before processing the search request, immedia ``` +## `withKeyboardShortcut` + +Enable opening and accessing the search input and their results with a keyboard shortcut. + +![Keyboard Shortcut Icon](./img/ra-search-keyboard-shortcut-icon.png) + +```tsx + +``` + +The default shortcut is `Ctrl+K` on Windows and Linux, and `Cmd+K` on MacOS. You can override this shortcut by passing the key combination as a string to the `withKeyboardShortcut` prop: + +```tsx + +``` + +You can also set multiple shortcuts: + +```tsx + +``` + +You can use the following modifiers and special keys: + +- `shift` +- `alt` +- `ctrl` +- `meta` +- `mod` (which listens for `ctrl` on Windows/Linux and `cmd` on macOS) +- `backspace` +- `tab` +- `clear` +- `enter` or `return` +- `esc` or `escape` +- `space` +- `up`, `down`, `left`, `right` +- `pageup`, `pagedown` +- `del` or `delete` +- `f1`, `f2` ... `f19` + +**Tip:** Upper case letters are considered lower case letters. To handle users pressing the letter `S` in capital letters, you must set `withKeyboardShortcut` to `shift+s`. + +**Tip:** If you override the default shortcut with an array of multiple shortcuts, the default shortcut icon will be your first shortcut. To edit it, you can update the [shortcut icon](#keyboardshortcuticon) as well. + ## Customizing The Result Items By default, `` displays the results in ``, which displays each results in a ``. So rendering `` without children is equivalent to rendering: diff --git a/docs/img/ra-search-keyboard-shortcut-icon.png b/docs/img/ra-search-keyboard-shortcut-icon.png new file mode 100644 index 00000000000..fda7f5efab3 Binary files /dev/null and b/docs/img/ra-search-keyboard-shortcut-icon.png differ