TanStack

React Example: Keyboard Layouts

import { TanStackDevtools } from '@tanstack/react-devtools'
import {
  HotkeysProvider,
  useFormatForDisplay,
  useHotkey,
} from '@tanstack/react-hotkeys'
import { hotkeysDevtoolsPlugin } from '@tanstack/react-hotkeys-devtools'
import React from 'react'
import ReactDOM from 'react-dom/client'
import type { GermanKeys, Hotkey, UsKeys } from '@tanstack/react-hotkeys'
import './index.css'

// Hotkey strings accept the keys that US and German keyboards type. Without
// this, only US keys type-check, and `Mod+Ö` is an error. This changes types
// only: matching works the same with or without it.
declare module '@tanstack/react-hotkeys' {
  interface Register {
    keys: UsKeys | GermanKeys
  }
}

const devtoolsPlugins = [hotkeysDevtoolsPlugin()]

interface Shortcut {
  hotkey: Hotkey
  name: string
}

// These type-check because German keys are registered above.
const germanShortcuts: Array<Shortcut> = [
  { hotkey: 'Mod+Ö', name: 'Toggle comment' },
  { hotkey: 'Mod+Shift+Ä', name: 'Add annotation' },
  { hotkey: 'ß', name: 'Toggle sidebar' },
  { hotkey: '§', name: 'Show sections' },
]

// A to Z, 0 to 9, named keys, and physical codes type-check under every
// registration, and fire on every layout.
const everyLayoutShortcuts: Array<Shortcut> = [
  { hotkey: 'Mod+K', name: 'Open command palette' },
  { hotkey: 'Alt+[Digit1]', name: 'Go to the first tab' },
  { hotkey: 'Escape', name: 'Clear' },
]

function ShortcutRow({
  shortcut,
  lastFired,
  onFire,
}: {
  shortcut: Shortcut
  lastFired: Hotkey | null
  onFire: (hotkey: Hotkey) => void
}) {
  const formatForDisplay = useFormatForDisplay()
  const [count, setCount] = React.useState(0)

  useHotkey(shortcut.hotkey, () => {
    setCount((c) => c + 1)
    onFire(shortcut.hotkey)
  })

  return (
    <div
      className={`hotkey-row ${lastFired === shortcut.hotkey ? 'fired' : ''}`}
    >
      <span>
        <kbd>{formatForDisplay(shortcut.hotkey)}</kbd> {shortcut.name}
      </span>
      <span className="count">{count}×</span>
    </div>
  )
}

function App() {
  const [lastFired, setLastFired] = React.useState<Hotkey | null>(null)

  const rows = (shortcuts: Array<Shortcut>) => (
    <div className="hotkey-list">
      {shortcuts.map((shortcut) => (
        <ShortcutRow
          key={shortcut.name}
          shortcut={shortcut}
          lastFired={lastFired}
          onFire={setLastFired}
        />
      ))}
    </div>
  )

  return (
    <div className="app">
      <header>
        <h1>Keyboard Layouts</h1>
        <p>
          Registering a layout lets hotkey strings accept the keys it types,
          such as Ö and ß. It changes types only: these hotkeys match the same
          way without it.
        </p>
      </header>

      <main>
        <section className="demo-section">
          <h2>German keys</h2>
          <p className="note">
            Switch your keyboard layout to German to press these.
          </p>
          {rows(germanShortcuts)}
        </section>

        <section className="demo-section">
          <h2>Keys on every layout</h2>
          {rows(everyLayoutShortcuts)}
        </section>

        <section className="demo-section">
          <h2>Usage</h2>
          <pre className="code-block">{`import type { GermanKeys, UsKeys } from '@tanstack/react-hotkeys'

declare module '@tanstack/react-hotkeys' {
  interface Register {
    keys: UsKeys | GermanKeys
  }
}

useHotkey('Mod+Ö', toggleComment) // OK
useHotkey('Mod+[', outdent) // OK, because UsKeys is listed
useHotkey('Mod+Ñ', x) // Type error: Spanish isn't registered`}</pre>
        </section>
      </main>

      <TanStackDevtools plugins={devtoolsPlugins} />
    </div>
  )
}

ReactDOM.createRoot(document.getElementById('root')!).render(
  <HotkeysProvider>
    <App />
  </HotkeysProvider>,
)