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.tsx
import { 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>
      <SearchInput
        ref={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#

hotkeysrequired

Type
HotkeysListOptions

Was this helpful?