# useShortcut

Runs a callback on a keyboard shortcut and formats the shortcut for the person's platform.

Source: [use-shortcut.ts](https://github.com/jakejarvis/jarvis-ui/blob/main/src/hooks/use-shortcut.ts)

```tsx
"use client";

import { SearchIcon } from "lucide-react";
import * as React from "react";

import { InputGroup, InputGroupAddon, InputGroupInput } from "@/components/ui/input-group";
import { Kbd, KbdGroup } from "@/components/ui/kbd";
import { useShortcut, useShortcutDisplay } from "@/hooks/use-shortcut";

export default function UseShortcutSearch() {
  const input = React.useRef<HTMLInputElement>(null);
  const display = useShortcutDisplay("Mod+K");
  useShortcut("Mod+K", () => input.current?.focus());

  return (
    <InputGroup className="max-w-sm">
      <InputGroupInput ref={input} placeholder="Search projects" aria-label="Search projects" />
      <InputGroupAddon>
        <SearchIcon />
      </InputGroupAddon>
      {display.keys.length > 0 && (
        <InputGroupAddon align="inline-end">
          <KbdGroup>
            {display.keys.map((key) => (
              <Kbd key={key}>{key}</Kbd>
            ))}
          </KbdGroup>
        </InputGroupAddon>
      )}
    </InputGroup>
  );
}
```

## Installation

Add the registry, once per project:

```bash
npx shadcn@latest registry add @jarvis=https://ui.jarv.is/r/{name}.json
```

Then add the hook:

```bash
npx shadcn@latest add @jarvis/use-shortcut
```

## Usage

```tsx
"use client";

import { Kbd } from "@/components/ui/kbd";
import { useShortcut, useShortcutDisplay } from "@/hooks/use-shortcut";

export function SaveHint({ onSave }: { onSave: () => void }) {
  const display = useShortcutDisplay("Mod+S");
  useShortcut("Mod+S", onSave);

  return <p>Save with {display.label && <Kbd>{display.label}</Kbd>}</p>;
}
```

A shortcut is a [TanStack Hotkeys](https://tanstack.com/hotkeys) chord, such as `Mod+K` or
`Mod+Shift+P`, where `Mod` is `⌘` on a Mac and `Ctrl` elsewhere. `useShortcut` runs a callback
when the chord is pressed. It's TanStack Hotkeys'
[`useHotkey`](https://tanstack.com/hotkeys/latest/docs/framework/react/reference/functions/useHotkey),
renamed to match `useShortcutDisplay`, so its options are documented there. They include `target`,
to listen inside one element, and `enabled`.

`useShortcutDisplay` formats a chord for the person's platform in two forms: `keys`, one label per
key for a [Kbd Group](https://ui.jarv.is/components/kbd.md), and `label`, all the keys in one string for a single `Kbd`.
For example, `⌘K` on a Mac and `Ctrl+K` elsewhere. The server can't detect the platform, so both
stay empty until the page hydrates. The example shows no keys until then rather than guessing and
correcting itself. [Command](https://ui.jarv.is/components/command.md) uses both hooks to display and bind its items'
shortcuts.

## API

### useShortcut

`useShortcut(shortcut, callback, options?)` is TanStack Hotkeys' `useHotkey`.

### useShortcutDisplay

`useShortcutDisplay(shortcut)` takes a chord and returns its keys, which stay empty until the page
hydrates:

| Value   | Type       | Description                                                                                                                   |
| ------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `keys`  | `string[]` | One label per key, such as `⌘` and `K`, for a `KbdGroup`. Empty until the page hydrates.                                      |
| `label` | `string`   | The keys as a single string, such as `⌘K` on a Mac and `Ctrl+K` elsewhere, for a single `Kbd`. Empty until the page hydrates. |

The file also exports `ShortcutChord`, the type of a chord.
