Keyboard Map
A rendered keyboard with highlighted keys and chords: the visual big sibling of Kbd and Hotkey, for shortcut documentation and editor cheat sheets.
<arc-keyboard-map>Overview
Keyboard Map draws a full keyboard as a grid of keycaps and lights up the keys named in its highlight prop. Where Kbd names a key inline and Hotkey listens for one invisibly, Keyboard Map shows a chord in its physical context. Cmd+Shift+P stops being three tokens in a sentence and becomes three glowing caps on a board, which is how people remember shortcuts. Highlighted keys carry the house state marking: accent tint, glow, and accent legend text.
The highlight prop accepts chords as an array property (["mod+z", "mod+shift+z"]) or as a comma- or space-separated attribute string. Chord syntax follows Hotkey's conventions: keys join with "+", cmd/command normalize to meta, option to alt, and mod resolves to Cmd on Mac and Ctrl on Windows so one chord string documents both platforms. The platform prop controls modifier legends and mod resolution: "auto" detects the visitor's platform in the browser (and renders the Mac board on the server), while "mac" and "win" pin it. Two layouts cover the documentation cases: compact (the default) is a 60%-style block without nav cluster or numpad, and ansi adds the F-row and nav cluster. The board is a stylised diagram. It has no ISO/JIS machinery, because chasing physical-layout fidelity would trade legibility for configuration surface.
The component is pure display typography: no slots, no click events, nothing focusable. A shortcut diagram that responded to clicks would imply the keys do something, and wiring real shortcuts is Hotkey's job. The two compose naturally, one listening while the other documents. Accessibility follows the diagram model: the board is a single role="img" whose label is computed from the chords ("Keyboard diagram highlighting Cmd+Shift+P"), and the individual key legends are hidden from assistive technology. The board scales to its container; --keyboard-map-key overrides the key size, and legends step out below ~340px where they would be unreadable noise.
Guidelines
When to use
- Use Keyboard Map for cheat sheets and settings pages where seeing a chord on the board beats reading it. Kbd stays the right tool for a shortcut mentioned inline in a sentence
- Write chords with `mod` (mod+shift+p) so one string documents Cmd on Mac and Ctrl on Windows
- Pair it with Hotkey: Hotkey wires the shortcut, Keyboard Map documents it
- Group related chords on one board (undo and redo together) and give each board a caption naming the group
- Prefer the compact layout. Reach for ansi only when a chord actually uses the F-row or nav cluster
When not to use
- Do not use it as an input device or key tester. It is documentation typography: non-interactive, and it renders no click events
- Do not put one board per shortcut in running prose. That is Kbd’s job; a board earns its space by showing several related chords in context
- Do not expect ISO, JIS, or numpad geometry. The diagram is stylised, and unknown layout values fall back to compact
- Do not rely on the highlight alone to document a shortcut for screen reader users. The computed label names the chords, but the surrounding text should too
Features
- Chord highlighting with accent tint, glow, and accent legend text (the house state marking)
- Platform-aware `mod` (Cmd on Mac, Ctrl on Windows) and modifier legends (⌘ ⌥ ⇧ ⌃ vs Ctrl/Alt/Shift/Win), following Hotkey’s normalization
- Two layouts: compact (60%-style, the default) and ansi (adds F-row and nav cluster)
- Highlight as an array property or a comma/space-separated attribute string; unknown key names are ignored
- Optional caption below the board in muted text
- role="img" with an aria-label computed from the chords; key legends hidden from assistive tech
- Scales to its container; `--keyboard-map-key` and `--keyboard-map-gap` tune the geometry
- Server-renders deterministically: platform detection waits for the browser, defaulting to Mac
Preview
Usage
<!-- Chords as an attribute string; mod = Cmd on Mac, Ctrl on Windows -->
<arc-keyboard-map highlight="mod+z, mod+shift+z" caption="Undo and redo"></arc-keyboard-map>
<!-- Full board with F-row and nav cluster, pinned to Windows legends -->
<arc-keyboard-map layout="ansi" platform="win" highlight="alt+f4"></arc-keyboard-map>
<!-- Chords as an array property -->
<arc-keyboard-map id="palette-map"></arc-keyboard-map>
<script type="module">
document.getElementById('palette-map').highlight = ['mod+shift+p', 'escape'];
</script>import { KeyboardMap } from '@arclux/arc-ui-react';
<KeyboardMap highlight={['mod+z', 'mod+shift+z']} caption="Undo and redo" />
<KeyboardMap layout="ansi" platform="win" highlight="alt+f4" /><script setup>
import { KeyboardMap } from '@arclux/arc-ui-vue';
</script>
<template>
<KeyboardMap :highlight="['mod+z', 'mod+shift+z']" caption="Undo and redo" />
<KeyboardMap layout="ansi" platform="win" highlight="alt+f4" />
</template><script>
import { KeyboardMap } from '@arclux/arc-ui-svelte';
</script>
<KeyboardMap highlight={['mod+z', 'mod+shift+z']} caption="Undo and redo" />
<KeyboardMap layout="ansi" platform="win" highlight="alt+f4" />import { Component } from '@angular/core';
import { KeyboardMap } from '@arclux/arc-ui-angular';
@Component({
imports: [KeyboardMap],
template: `
<arc-keyboard-map highlight="mod+z, mod+shift+z" caption="Undo and redo" />
<arc-keyboard-map layout="ansi" platform="win" highlight="alt+f4" />
`,
})
export class ShortcutsComponent {}import { KeyboardMap } from '@arclux/arc-ui-solid';
<KeyboardMap highlight={['mod+z', 'mod+shift+z']} caption="Undo and redo" />
<KeyboardMap layout="ansi" platform="win" highlight="alt+f4" />import { KeyboardMap } from '@arclux/arc-ui-preact';
<KeyboardMap highlight={['mod+z', 'mod+shift+z']} caption="Undo and redo" />
<KeyboardMap layout="ansi" platform="win" highlight="alt+f4" />API
layout'compact' | 'ansi''compact'- Board shape: "compact" (default, a 60%-style block) or "ansi" (adds the F-row and nav cluster). Unknown values fall back to compact.
highlightstring|string[]''- Key chords to light up: an array property (e.g. ["mod+z", "mod+shift+z"]) or a comma- or space-separated attribute string. Each chord joins keys with "+" ("mod+shift+p");
modresolves to Cmd on mac and Ctrl on win, mirroring arc-hotkey's aliases (cmd/command → meta, option → alt, control → ctrl). Single keys are fine ("g", "escape"). Unknown key names are ignored. labelsbooleantrue- Whether keys render their legends. Default true; disable from markup with either
no-labelsorlabels="false". platform'auto' | 'mac' | 'win''auto'- Which platform's modifier legends and
modresolution to use: "auto" (default, detected in the browser, mac on the server), "mac", or "win". captionstring''- Optional caption rendered below the board in muted text.