Utilities

useCommandShortcut

A hook that runs a function when the user presses the command key or the control key with a letter.

import * as React from 'react'
import { Button, CommandMenu, Kbd, toast, useCommandShortcut, useModKey, type CommandMenuGroup } from 'ferry-ui'
import { FolderKanban, Receipt, Users } from 'lucide-react'

const GROUPS: CommandMenuGroup[] = [
  {
    id: 'pages',
    label: 'Go to',
    items: [
      { id: 'projects', label: 'Projects', icon: <FolderKanban />, onSelect: () => toast('Projects') },
      { id: 'members', label: 'Members', icon: <Users />, onSelect: () => toast('Members') },
      { id: 'invoices', label: 'Invoices', icon: <Receipt />, onSelect: () => toast('Invoices') },
    ],
  },
]

export default function UseCommandShortcutHero() {
  const [open, setOpen] = React.useState(false)
  const mod = useModKey()
  // The letter J: this site already binds the letter K to its search.
  useCommandShortcut(() => setOpen((current) => !current), 'j')
  return (
    <>
      <Button onClick={() => setOpen(true)}>
        Open the menu <Kbd>{mod} J</Kbd>
      </Button>
      <CommandMenu open={open} onOpenChange={setOpen} groups={GROUPS} />
    </>
  )
}

Usage#

Call the hook one time, near the root of the app. Put it next to the state of your Command Menu. With no second argument, the shortcut is ⌘ K on an Apple device and Ctrl K on other devices.

import * as React from 'react'
import { CommandMenu, useCommandShortcut, type CommandMenuGroup } from 'ferry-ui'

export function SearchEverywhere({ groups }: { groups: CommandMenuGroup[] }) {
  const [open, setOpen] = React.useState(false)
  useCommandShortcut(() => setOpen((current) => !current))
  return <CommandMenu open={open} onOpenChange={setOpen} groups={groups} />
}

The shortcut works in the full window. It also works when the focus is in a text field.
The browser does not get the shortcut. The hook stops the default action of the browser.
The modifier keys matter. The hook ignores a press with Shift or Alt.
The hook shows no key. To show the keys, use Kbd with useModKey() from usePlatform.
Not for one widget. For a shortcut that works only in one widget, use onKeyDown on this widget.

Bind each letter in one place

App Shell calls this hook for its onCommandShortcut prop. CommandMenu calls it for its shortcut prop. Use only one of the three for a letter. If not, each press runs more than one handler.

Examples#

Another letter#

Pass a letter as the second argument. The case of the letter does not matter. For two letters, call the hook two times.

useCommandShortcut(openInvoiceSearch, 'j')

Shortcut on and off#

Pass an object with enabled. While enabled is false, the hook does not listen.

Press Ctrl UPresses: 0

Shortcut enabled

import * as React from 'react'
import { Kbd, Label, Switch, useCommandShortcut, useModKey } from 'ferry-ui'

export default function UseCommandShortcutEnabled() {
  const [enabled, setEnabled] = React.useState(true)
  const [count, setCount] = React.useState(0)
  const mod = useModKey()
  // The hook listens only while `enabled` is true.
  useCommandShortcut(() => setCount((current) => current + 1), { key: 'u', enabled })
  return (
    <div className="flex flex-col items-center gap-4">
      <p className="flex items-center gap-2 text-sm text-foreground-light">
        Press <Kbd>{mod} U</Kbd>
        <span className="text-foreground tabular">Presses: {count}</span>
      </p>
      <div className="flex items-center gap-2">
        <Switch id="shortcut-enabled" checked={enabled} onCheckedChange={setEnabled} />
        <Label htmlFor="shortcut-enabled">Shortcut enabled</Label>
      </div>
    </div>
  )
}

API reference#

useCommandShortcut(handler, options) returns nothing.

Parameter	Type	Role
`handler`	`(event: KeyboardEvent) => void`	Runs on each press. The hook always calls the latest function.
`options`	`string \| CommandShortcutOptions`	Optional. A letter, or an object with the options below.

Option	Type	Default	Role
`key`	`string`	`'k'`	The letter of the shortcut.
`enabled`	`boolean`	`true`	The hook listens only while the value is `true`.