Kbd
Kbd shows a keyboard shortcut as a row of keys. It names symbol keys for screen readers and shows ⌘ on a Mac and Ctrl elsewhere.
<tk-kbd keys="Mod+K"></tk-kbd> <tk-kbd keys="Mod+Shift+P"></tk-kbd> <tk-kbd keys="Esc"></tk-kbd>
Anatomy
| Part | What it is |
|---|---|
tk-kbd |
the element; inline, not focusable, no role |
key part |
each key, a native <kbd> |
separator part |
the + between keys, in bare only |
A symbol key such as ⌘ or ↑ shows the symbol and gives screen readers a word, such as
"Command" or "Up arrow". A letter or word key, such as K or F5, is plain text.
Variants
<tk-kbd keys="Mod+K"></tk-kbd> <tk-kbd keys="Mod+K" treatment="bare"></tk-kbd>
chip(default): each key on a soft filled plate. Use it where the shortcut is the point: palette footers, tips, cheat sheets.bare: quiet secondary text with+between keys. Use it where the shortcut trails a label, such as in thetrailingslot of aMenu item.
Keys
Write the keys in the keys attribute, joined by +. Case doesn't matter for named keys.
| Write | Shows on a Mac | Shows elsewhere |
|---|---|---|
Mod |
⌘ | Ctrl |
Ctrl, Control |
⌃ | Ctrl |
Alt, Option, Opt |
⌥ | Alt |
Shift |
⇧ | Shift |
Cmd, Command |
⌘ | ⌘ |
Enter, Return |
⏎ | ⏎ |
Backspace / Delete, Del |
⌫ / ⌦ | ⌫ / ⌦ |
Up, Down, Left, Right |
↑ ↓ ← → | ↑ ↓ ← → |
Esc, Tab, Space |
the word | the word |
Anything else, such as K, 5, or F5, shows as written. Symbols typed directly, such
as ⌘ or ↵, are named for screen readers too.
A +, ,, or space key can't go in the attribute. Set the keys property to an array
instead, or write Space:
document.querySelector('tk-kbd').keys = ['Ctrl', '+'];Platform
<tk-kbd keys="Mod+S" platform="mac"></tk-kbd> <tk-kbd keys="Mod+S" platform="windows"></tk-kbd>
platform is auto by default: Kbd checks the reader's operating system. Set mac,
windows, or linux to fix it. windows and linux look the same.
- Use
Modfor the main modifier, the one that's ⌘ on a Mac and Ctrl elsewhere.Ctrlalways means the Control key, so on a Mac it shows ⌃, not ⌘. autosees the operating system, not the keyboard. A PC keyboard on a Mac, remapped keys, or a remote desktop can make it wrong. If your shortcut code decides the modifier another way, setplatformto match it.
When to use
- Use Kbd to show a shortcut: in a command palette footer, a tip, a button hint, or a menu item.
- It only shows the shortcut. It listens for no keys; your code handles the shortcut. Keep the two in sync.
- For one key inside prose, a
<kbd class="tk-kbd">is enough: seeProse . It looks the same. Usetk-kbdfor several keys, named symbols, or the platform swap.
Content
- Show the shortcut your code really handles, on the platform it handles it.
- Write keys in the order they're pressed: modifiers first, then the key.
- Use the key's own name:
Esc,Enter,F5. Don't invent labels.
Do / Don't
| ✅ Do | ❌ Don't |
|---|---|
Write Mod+K for the main modifier |
Write Ctrl+K; a Mac shows ⌃K |
Set platform when your code fixes the modifier |
Trust auto to know the keyboard |
Use bare in a menu item |
Put a loud chip next to a menu label |
| Show the shortcut your code handles | Treat Kbd as the shortcut itself |
Set a + key through the keys property |
Write a + key in the attribute |
Related
Prose : the.tk-kbdclass for a single key.Menu : thetrailingslot for a shortcut hint.Code block : code, not keys.
API
Attributes
| Attribute | Type | Default | What it does |
|---|---|---|---|
keys |
+-separated string; or an array as a property |
none | the keys of the shortcut |
platform |
auto | mac | windows | linux |
auto |
which platform's modifiers to show |
treatment |
chip | bare |
chip |
key plates or quiet text |
Slots
None. The keys come from keys.
Events
None. Kbd isn't interactive.
CSS
::part(key): each<kbd>.::part(separator): the+inbare.
Tokens
| Treatment | Tokens |
|---|---|
chip |
surface/subtle plate, radius-4 corner, space-6 inline padding, no border; space-4 between keys; text in the surrounding color, mono, at 0.875em |
bare |
text/secondary, the surrounding font; space-4 around each + |
The chip is the same style as the .tk-kbd class. Values per theme:
Accessibility
Built in:
- Each key is a real
<kbd>. - Symbol keys are named for screen readers: ⌘ is read as "Command", not as the symbol's Unicode name.
- The
+separator is hidden; a screen reader hears "Command K". - Kbd takes no focus and has no role, so it never traps focus.
Your part:
- Use
Mod, notCtrl, for the main modifier. - Set
platformwhen your shortcut code may disagree with the detected system. - Make the shortcut itself accessible. A shortcut that is a single character must be possible to turn off, remap, or limit to when its control has focus (WCAG 2.1.4). That's the job of your code, not of Kbd.
Contrast limits
- The key text is at least 15:1 on the chip in light and high contrast, and 8.78:1 in
dark.
baretext istext/secondary, at least 4.5:1. - The chip's shape is faint: the plate is 1.09:1 against the page in light and 1.22:1 in high contrast. The key text still reads; if the key shape must stand out, place the chip on a plain page or card surface.
- Next to inline
code, the key chip is the softer of the two:codehas a hairline border and the chip doesn't.