HotkeysListOptions
Hotkeys
Keyboard shortcuts for modern apps
Keyboard shortcuts are an excellent way to support advanced users in your app to be more productive.
As you add more shortcuts to you app you can run into conflicts,
it can become a big mess if you don't keep track of which hotkeys are used and where.
Hotkeys
tries to solve this by having a single source of truth that defines
all available hotkeys throughout your app.
An extra benefit is that the documentation for your users can be generated and is always up to date.
Other features
- Supports shifted keys like ?, =, @.
- ⌥ ⇧ ⌃ ⌘ shorthands are supported.
- Won't trigger inside inputs / content editable elements.
- Hooks also work without a global config object.
- The HotkeysList can also be used to list other options, like markdown support.
Import#
import {useHotkeys,useHotkeysShortcut,HotkeysProvider,HotkeysList,} from '@saas-ui/react'
Usage#
Create a config object containing all the keyboard shortcuts in your app. The keys in the config can be used as shortcuts with the included hook throughout your app.
Configuration#
// app.tsximport { HotkeysProvider, HotkeysListOptions } from '@saas-ui/hotkeys'const hotkeys: HotkeysListOptions = {general: {title: 'General',hotkeys: {help: { label: 'Help', command: '?' },search: { label: 'Search', command: '⌘ K' },},}}export default const App = () => {return (<HotkeysProvider hotkeys={hotkeys}>{children}</HotkeysProvider>)}
Register shortcut actions#
useHotkeysShortcut
returns the command value and can be used to show the key combinations to your users.
export const MyComponent = () => {const help = useHotkeysShortcut('general.help', () => {onOpen()})useHotkeysShortcut('general.search', () => {searchRef.current?.focus()})return (<>Press <Kbd>{help}</Kbd> for help.</>)}
HotkeysList component#
function HotkeysListModal() {const searchRef = useRef(null)const { isOpen, onOpen, onClose } = useDisclosure()const help = useHotkeysShortcut('?' /* general.help */, () => {onOpen()})// for the sake of this example we don't depend on the hotkeys context here.// const { hotkeys } = useHotkeysContext()const hotkeys = {general: {title: 'General',hotkeys: {help: { label: 'Help', command: '?' },search: { label: 'Search', command: '⌘ K' },},},}return (<Box><Text>Press <strong>{help}</strong> for help</Text><Modal isOpen={isOpen} onClose={onClose} initialFocusRef={searchRef}><ModalOverlay /><ModalContent><ModalCloseButton /><ModalHeader>Keyboard shortcuts</ModalHeader><ModalBody><HotkeysList hotkeys={hotkeys}><HotkeysSearch ref={searchRef} /><HotkeysListItems /></HotkeysList></ModalBody></ModalContent></Modal></Box>)}
Stand alone usage#
useHotkeys
can also be used standalone.
function Dialog() {const searchRef = useRef(null)useHotkeys('⌘ K', () => {searchRef.current.focus()})return (<Box><SearchInputref={searchRef}pr="30px"rightElement={<Flex pos="absolute" right="4px"><Kbd bg="none" fontSize="lg">⌘</Kbd><Kbd bg="none" fontSize="lg">K</Kbd></Flex>}/></Box>)}
Multiple key combinations#
To target multiple platforms it's possible to pass an array of key combinations.
function Dialog() {const [isLoading, setLoading] = useState()const key = useHotkeys(['⌘ Enter', 'Ctrl+Enter'], () => {setLoading(true)setTimeout(() => setLoading(false), 2000)})return (<Box><Tooltip label="⌘ Enter" openDelay={500}><Button isLoading={isLoading}>Save</Button></Tooltip></Box>)}
Key sequences#
function Dialog() {const [isLoading, setLoading] = useState()const key = useHotkeys('A then S', () => {setLoading(true)setTimeout(() => setLoading(false), 2000)})return (<Box><Tooltip label={key} openDelay={500}><Button isLoading={isLoading}>Save</Button></Tooltip></Box>)}
Props#
useHotkeys Params#
useHotkeys
accepts a string
or array of strings string[]
and a callback function (e: KeyboardEvent) => void
useHotkeysShortcut Params#
useHotkeysShortcut
accepts a string
with the shortcut or a key combination and a callback function (e: KeyboardEvent) => void
HotkeysList Props#
hotkeys
required
hotkeys
required
Was this helpful?