data-hotkey
Platform-aware keyboard shortcut display and declarative action binding. On <kbd> elements renders platform symbols; on other elements binds keyboard shortcuts to actions.
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
- Reads the
data-hotkeyattribute value (e.g.,"meta+k") - Detects the user's platform (Mac vs. other)
- Maps modifier names to platform-appropriate symbols or labels
- Generates a
<kbd>element for each key in the combo - Replaces the element's content with the styled key caps
- Sets
aria-labelwith 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:
<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 <tool-tip> to show shortcuts on hover:
<tool-tip> <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></tool-tip>Dynamic Elements
Elements added to the DOM after page load are automatically enhanced via a MutationObserver. No manual initialization is needed.
<section> <h2>Action Binding</h2> <p>When <code>data-hotkey</code> is placed on a non-<code><kbd></code> element (button, input, details, etc.), it binds an actual keyboard shortcut that triggers an action on the element. This upscales the native <code>accesskey</code> attribute with cross-platform modifier normalization and conflict detection.</p> <browser-window src="/docs/examples/demos/hotkey-action-basic.html" url="https://vanilla-breeze.dev/hotkey-actions" title="Hotkey Actions" shadow> </browser-window> <code-block language="html" show-lines label="Bind a shortcut to a button" data-escape><button data-hotkey="meta+s" data-hotkey-label="Save document" data-hotkey-global> Save <kbd data-hotkey="meta+s"></kbd></button>Action binding attributes
| Attribute | Value | Description |
|---|---|---|
data-hotkey-action |
string | Action type: "click" (default), "focus", "submit", "toggle". |
data-hotkey-label |
string | Description for the shortcuts dialog. Defaults to element text content. |
data-hotkey-group |
string | Group name in shortcuts dialog. Default: "Page Actions". |
data-hotkey-global |
boolean | If present, fires even when typing in an input field. |
Action types
| Action | Behavior | Use Case |
|---|---|---|
click |
Triggers .click() |
Buttons, links |
focus |
Moves focus to element | Search inputs |
submit |
Submits closest form | Save shortcuts |
toggle |
Toggles open or hidden |
Panels, drawers |
Focus search on /
<input type="search" data-hotkey="/" data-hotkey-action="focus" data-hotkey-label="Focus search">Toggle a details panel
<details data-hotkey="meta+i" data-hotkey-action="toggle" data-hotkey-label="Toggle info panel"> <summary>Info</summary> <p>Panel content.</p></details>Shortcuts dialog integration
All hotkey-bound elements automatically appear in the <short-cuts> overlay (press ? to open). Add <short-cuts></short-cuts> once in your page to enable it.
Accessibility
- Sets
aria-labelon 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