Component
Keyboard shortcut
A key or key combination, shown inline, in a control, or in a list of shortcuts.
Plain-text source, for agents and clipboard use: /components/source/kbd.txt
When to use it
Tells people which keys do something. It is the kbd element in mono on layer-02 with a hairline. Write shortcuts with Apple symbols and add data-flux-keys: on other platforms flux-components.js rewrites ⌘ as Ctrl and ⌥ as Alt, so the hint matches the keyboard in front of the reader.
Not this
Not for a shortcut that does not exist; a hint promises behaviour. Not for code or identifiers; use mono text or code. Not as a button.
Examples
Inline
Press ⌘K to search, or ? to see every shortcut.
html
<p>Press <kbd class="flux-kbd" data-flux-keys>⌘K</kbd> to search, or <kbd class="flux-kbd">?</kbd> to see every shortcut.</p>In a button
The hint is hidden from assistive technology and the shortcut is declared with aria-keyshortcuts instead.
html
<button class="flux-button flux-button--secondary" type="button" aria-keyshortcuts="Meta+S">Save draft <kbd class="flux-kbd" data-flux-keys aria-hidden="true">⌘S</kbd></button>Shortcut list
- Search
- ⌘K
- Save changes
- ⌘S
- Next record
- J
- Previous record
- K
- Show shortcuts
- ?
html
<dl class="flux-shortcuts">
<div><dt>Search</dt><dd><kbd class="flux-kbd" data-flux-keys>⌘K</kbd></dd></div>
<div><dt>Save changes</dt><dd><kbd class="flux-kbd" data-flux-keys>⌘S</kbd></dd></div>
<div><dt>Next record</dt><dd><kbd class="flux-kbd">J</kbd></dd></div>
<div><dt>Previous record</dt><dd><kbd class="flux-kbd">K</kbd></dd></div>
<div><dt>Show shortcuts</dt><dd><kbd class="flux-kbd">?</kbd></dd></div>
</dl>Anatomy
| Part | Description |
|---|---|
| Key | A kbd at text-xs mono 500, not uppercase, on layer-02 with a hairline and 4px radius. |
| Shortcut list | A dl.flux-shortcuts: the action as the term, its keys as the detail, divided by hairlines. |
API
| Name | Kind | Description |
|---|---|---|
kbd | element | The native element for keyboard input. |
flux-kbd | class | On the kbd. Inside a menu item or command option it aligns to the end. |
data-flux-keys | attribute | Rewrites ⌘ as Ctrl, ⌥ as Alt, ⌃ as Ctrl and ⇧ as Shift on platforms other than Apple’s. |
flux-shortcuts | class | On a dl listing shortcuts, one div per action. |
aria-keyshortcuts | attribute | On the control the shortcut triggers, e.g. Meta+S. |
States
| State | Treatment |
|---|---|
| Apple platforms | Symbols as written. |
| Other platforms | Modifier names, e.g. Ctrl K. |
Keyboard
| Keys | Action |
|---|---|
None | A hint is not focusable. The shortcut itself is handled by the product. |
Accessibility
- Declare a control’s shortcut with aria-keyshortcuts and hide the visual hint inside it, so the accessible name stays “Save draft”.
- Never bind a single printable key without a way to turn it off or remap it (WCAG 2.1.4); J and K only apply when focus is not in a field.
Tokens
The tier-3 and tier-2 tokens this component binds to. Change the token, not the component.
- --flux-kbd-bg | -border | -text | -padding-x | -gap
Do and don’t
Do
- Show the shortcut where the action is, in its menu item or button.
- Keep one list of every shortcut, opened with ?.
Don’t
- Do not uppercase keys or letter-space them; a kbd is not a structural label.
- Do not override a browser or screen-reader shortcut.