data-hotkey

Platform-aware keyboard shortcut display. Add data-hotkey to any <kbd> element to render platform-appropriate key symbols.

Overview

The data-hotkey attribute enhances native <kbd> elements with platform-aware key rendering. On Mac, modifier keys display as symbols; on other platforms, as text labels with + separators.

<kbd data-hotkey="meta+k">Ctrl+K</kbd>

How It Works

  1. Reads the data-hotkey attribute value (e.g., "meta+k")
  2. Detects the user's platform (Mac vs. other)
  3. Maps modifier names to platform-appropriate symbols or labels
  4. Generates a <kbd> element for each key in the combo
  5. Replaces the element's content with the styled key caps
  6. Sets aria-label with the readable text

The original text content (e.g., "Ctrl+K") serves as a no-JS fallback. Nested <kbd> inside <kbd> is valid HTML for key combinations per the spec.

Attributes

Attribute Type Description
data-hotkey string Key combination string. Keys separated by +. Supported modifiers: meta, alt, shift, ctrl.
data-hotkey-init boolean Set automatically to prevent double-enhancement. Do not set manually.

Modifier Key Mapping

Modifier keys are automatically translated based on the user's platform:

Key name Mac Windows/Linux
meta ⌘ Ctrl
alt ⌥ Alt
shift ⇧ Shift
ctrl ⌃ Ctrl

Non-modifier keys are displayed in uppercase (e.g., k becomes K).

Examples

Common keyboard shortcuts rendered with platform-aware symbols:

Search: Ctrl+K Save: Ctrl+S Undo: Ctrl+Z Command palette: Ctrl+Shift+P
<kbd data-hotkey="meta+k">Ctrl+K</kbd> <kbd data-hotkey="meta+s">Ctrl+S</kbd> <kbd data-hotkey="meta+shift+p">Ctrl+Shift+P</kbd> <kbd data-hotkey="alt+f4">Alt+F4</kbd>

Inline Usage

Works naturally inline with paragraph text:

Press Ctrl+K to open the search palette.

Use Ctrl+Shift+P for the command palette.

<p>Press <kbd data-hotkey="meta+k">Ctrl+K</kbd> to open the search palette.</p>

Common Use Cases

Keyboard Shortcuts Table

Display a reference table of available shortcuts:

Action Shortcut
Search Ctrl+K
Save Ctrl+S
Undo Ctrl+Z
Redo Ctrl+Shift+Z
Select all Ctrl+A
<table> <tbody> <tr> <td>Search</td> <td><kbd data-hotkey="meta+k">Ctrl+K</kbd></td> </tr> <tr> <td>Save</td> <td><kbd data-hotkey="meta+s">Ctrl+S</kbd></td> </tr> <tr> <td>Undo</td> <td><kbd data-hotkey="meta+z">Ctrl+Z</kbd></td> </tr> </tbody> </table>

With Tooltips

Combine with <tooltip-wc> to show shortcuts on hover:

<tooltip-wc> <button type="button"> <icon-wc name="search" size="sm"></icon-wc> Search </button> <template data-tooltip> Search <kbd data-hotkey="meta+k">Ctrl+K</kbd> </template> </tooltip-wc>

Dynamic Elements

Elements added to the DOM after page load are automatically enhanced via a MutationObserver. No manual initialization is needed.

// Dynamically added elements are auto-enhanced via MutationObserver const kbd = document.createElement('kbd'); kbd.dataset.hotkey = 'meta+n'; kbd.textContent = 'Ctrl+N'; document.body.appendChild(kbd); // kbd is enhanced automatically — no manual init needed

Accessibility

  • Sets aria-label on the element with the full text content for screen readers
  • Uses semantic <kbd> elements which are recognized by assistive technology
  • Nested <kbd> inside <kbd> is valid HTML for key combinations per the spec
  • The original text content serves as a no-JS fallback
  • On Mac, separators between keys are omitted since the symbols are self-explanatory; on other platforms, + separators are included for clarity