Shortcut

c2-shortcut turns key presses into actions. It renders nothing: one element holds every shortcut of an application (or of one region) in its bindings list, and a single shortcut event tells you which one fired, so the app has one listener and one switch. A binding can also click or focus another element through for, which needs no script at all.

Import

import '@c2n/components/shortcut'

Usage

Press alt + 1, alt + 2 or alt + 3 (⌥ on macOS) anywhere on this page to flip the switches. Every shortcut holds Ctrl, ⌘ or Alt, so none of them gets in the way of typing.

import '@c2n/components/shortcut'
import '@c2n/components/switch'
import '@c2n/components/kbd'

<style>
  .shortcut-demo {
    display: grid;
    gap: 10px;
    width: 280px;
    max-width: 100%;
    font-size: 14px;
    color: var(--c2-theme--color-on-surface, #18181b);
  }
  .shortcut-demo__row {
    display: flex;
    align-items: center;
    justify-content: space-between;
    gap: 16px;
  }
</style>
<div data-label="Activating targets">
  <div class="shortcut-demo">
    <c2-shortcut
      bindings='[{"keys":"alt+1","for":"shortcut-demo-wifi"},{"keys":"alt+2","for":"shortcut-demo-bluetooth"},{"keys":"alt+3","for":"shortcut-demo-airplane"}]'
    ></c2-shortcut>
    <div class="shortcut-demo__row"><c2-switch id="shortcut-demo-wifi" checked>Wi-Fi</c2-switch><c2-kbd>alt + 1</c2-kbd></div>
    <div class="shortcut-demo__row"><c2-switch id="shortcut-demo-bluetooth">Bluetooth</c2-switch><c2-kbd>alt + 2</c2-kbd></div>
    <div class="shortcut-demo__row"><c2-switch id="shortcut-demo-airplane">Airplane mode</c2-switch><c2-kbd>alt + 3</c2-kbd></div>
  </div>
</div>

One element for the whole application

List every shortcut once and switch on detail.action. Assigning a new array to bindings replaces them all, which is how an app swaps its shortcuts per route.

<c2-shortcut
  id="shortcuts"
  bindings='[
    { "keys": "mod+k, mod+/", "action": "search", "description": "Open search" },
    { "keys": "mod+s", "action": "save", "description": "Save" },
    { "keys": "alt+g alt+d", "action": "go-dashboard", "description": "Go to dashboard" },
    { "keys": "escape", "action": "close-panel", "scope": ".side-panel", "allowInInputs": true },
    { "keys": "alt+n", "for": "new-item", "description": "New item" }
  ]'
></c2-shortcut>

<script type="module">
  import '@c2n/components/shortcut'

  const shortcuts = document.querySelector('#shortcuts')
  shortcuts.addEventListener('shortcut', (event) => {
    switch (event.detail.action) {
      case 'search':
        openSearch()
        break
      case 'save':
        save()
        break
      case 'go-dashboard':
        router.go('/dashboard')
        break
    }
  })
</script>

From script, a binding can carry a handler instead of an action, and entries returns each binding with its platform-aware label (⌘K, ⌘/ on macOS, Ctrl+K, Ctrl+/ elsewhere) for a cheatsheet:

shortcuts.bindings = [...shortcuts.bindings, { keys: 'mod+shift+?', handler: () => cheatsheet.show(), description: 'Show shortcuts' }]

for (const { label, description } of shortcuts.entries) console.log(label, description)

Key syntax

Every stroke must hold Ctrl, ⌘ or Alt (mod counts; Shift alone does not, since shift+a is typing). Escape and F1–F24 are the only exceptions. An alternative with a bare key (/, g d, shift+?) is ignored with a console warning. Key names are KeyboardEvent.key values, case-insensitive.

Letters and digits also match by physical key when the typed character is not plain ASCII, so alt+k works with Option on macOS and on non-Latin layouts.

Behaviour

• Typing. Shortcuts with Ctrl, ⌘ or Alt fire in fields too. Escape and the function keys, which need no modifier, are ignored while focus is in an input, textarea, select or contenteditable; allowInInputs lifts that guard for one binding.
• Scope. scope: "parent" limits a binding to focus inside the element’s parent; any other value is a CSS selector matched against the focused element and its ancestors. When several bindings match, the most narrowly scoped one wins, across every c2-shortcut on the page, then the first one listed.
• Firing. The key event’s default is prevented (allowDefault opts out), then shortcut fires on the element. Unless it is cancelled, the binding’s handler runs and its for target is activated: a text field — native or a component wrapping one, such as c2-text-field — is focused, anything else is clicked. For a component such as c2-switch or c2-button, the control inside its shadow root is clicked, so it toggles or activates as a real click would.
• Keys already handled. A key another component has handled (it called preventDefault(), as a list does for its arrow keys) is left alone.
• Held keys. Auto-repeat is ignored unless the binding sets repeat.
• Accessibility. Each for target receives aria-keyshortcuts (unless it already has one) so assistive technology announces the shortcut. Show the shortcut visually with c2-kbd.
• Pausing. disabled on the element pauses all of its bindings; disabled on a binding turns that one off. Removing the element unregisters everything.