Kbd

Data displaySince 0.9.0

import { Kbd } from '@absoluteui/components/kbd';
import '@absoluteui/components/kbd/style.css';

Using Angular? See Kbd for Angular.

What it does

Shows a keyboard shortcut such as “Ctrl+S” as keycaps. Kbd takes the hotkey syntax of matchesHotkey from @absoluteui/utilities (“Mod+Shift+K”), so a shortcut is written once and displayed for the user’s platform: on Apple platforms Mod is Command and modifiers show as symbols, each followed by its name for assistive technology; elsewhere Mod is Ctrl and keys are joined by “+”. It only displays; it never listens for keys.

When to use

• Documenting a shortcut next to the command it triggers: menu items, tooltips, help pages.
• Showing a key the user should press, such as Esc or Enter.

When not to use

• Code or command-line text: use a code element.
• Interactive key remapping: Kbd only displays.

Examples

Shortcuts for the current platform

import { Kbd } from '@absoluteui/components/kbd';

const list = document.createElement('ul');
document.body.append(list);
const shortcuts: [string, string][] = [['Save', 'Mod+S'], ['Command palette', 'Mod+Shift+P'], ['Close dialog', 'Esc'], ['Next row', 'ArrowDown']];
for (const [command, hotkey] of shortcuts) {
  const item = document.createElement('li');
  const keys = document.createElement('span');
  item.append(`${command}: `, keys);
  list.append(item);
  Kbd.create(keys, { hotkey });
}

The same shortcut on Apple and other platforms

import { Kbd } from '@absoluteui/components/kbd';

for (const platform of ['apple', 'other'] as const) {
  const line = document.createElement('p');
  const keys = document.createElement('span');
  line.append(`${platform === 'apple' ? 'macOS' : 'Windows and Linux'}: `, keys);
  document.body.append(line);
  Kbd.create(keys, { hotkey: 'Mod+Alt+Shift+K', platform });
}

Usage

import { Kbd } from '@absoluteui/components/kbd';
import '@absoluteui/components/kbd/style.css';

const host = document.querySelector<HTMLElement>('#palette-shortcut');
if (host) Kbd.create(host, { hotkey: 'Mod+Shift+P' });

More usage

import { Kbd } from '@absoluteui/components/kbd';
import { matchesHotkey } from '@absoluteui/utilities';

const SAVE = 'Mod+S';
const hint = document.querySelector<HTMLElement>('#save-shortcut');
if (hint) Kbd.create(hint, { hotkey: SAVE });
document.addEventListener('keydown', (event) => {
  if (matchesHotkey(event, SAVE)) event.preventDefault();
});

Anatomy

<span class="aui-kbd aui-kbd--{size}">
  <kbd class="aui-kbd__combo">
    <kbd class="aui-kbd__key">Ctrl</kbd>
    <span class="aui-kbd__separator">+</span>        (not on Apple platforms)
    <kbd class="aui-kbd__key">
      <span aria-hidden="true">symbol</span><span>Name (visually hidden)</span>   (symbol keys)
    </kbd>
  </kbd>
</span>

API reference

Factory

Kbd.create(host: HTMLElement, options: KbdOptions): Kbd

Global configuration key: kbd (see Configuration).

Options

Option	Type	Default	Description
hotkey	string		Shortcut in matchesHotkey syntax, such as ‘Mod+Shift+K’; ‘Plus’ is the + key. Required.
platform	'auto' | 'apple' | 'other'	"auto"	Apple shows Command for Mod and modifier symbols; other shows Ctrl and ‘+’ separators; auto detects. Globally configurable.
size	'sm' | 'md'	"md"	Keycap size. Globally configurable.
locale	string	"en-US"	Locale of key names. Globally configurable. Inherited from common configuration.

Properties

Property	Type	Description
host	HTMLElement	The host element (receives the classes).
hotkey	string	Current hotkey string.
text	string	The visible shortcut text for the resolved platform.
options	Readonly<KbdOptions>	Current options.

Methods

Method	Description
update(options: Partial<KbdOptions>): void	Merge and apply options.
destroy(): void	Remove rendering, classes, and the configuration subscription.

CSS classes

All rules live in the aui.components cascade layer, so application styles override them without specificity battles.

Class	Purpose
aui-kbd	Host.
aui-kbd--sm | --md	Size modifiers.
aui-kbd__combo	Outer kbd element for the combination.
aui-kbd__key	One keycap (kbd).
aui-kbd__separator	‘+’ between keycaps (not on Apple platforms).

Design tokens

Tokens this stylesheet reads (verified in CI). Override them in a theme or with the Theme Designer.

--aui-border-width | --aui-color-border-strong | --aui-color-surface-sunken | --aui-color-text | --aui-color-text-muted | --aui-font-family-mono | --aui-font-family-sans | --aui-font-size-sm | --aui-font-size-xs | --aui-line-height-tight | --aui-radius-sm | --aui-space-1

TypeScript definitions

type KbdPlatform = 'auto' | 'apple' | 'other';
type KbdSize = 'sm' | 'md';
interface KbdConfig { platform: KbdPlatform; size: KbdSize }
interface KbdOptions extends Partial<KbdConfig> {
  hotkey: string;
  locale?: string;
}

Accessibility

Pattern: Keyboard input markup: a kbd element for the combination with one nested kbd per key (HTML kbd semantics).

Keyboard

Key	Context	Action
None	Any	Not focusable; read in document order by assistive technology.

Roles

Element	Role
combination and keys	none (kbd text semantics)
symbol glyphs	none (aria-hidden=true; a visually hidden name follows)

ARIA attributes

Attribute	Element	Value
aria-hidden	Apple modifier and arrow symbols	true; the key name is provided as visually hidden text

Focus

Never receives or moves focus.

WCAG 2.2 success criteria addressed

Criterion	Level	Note
1.1.1 Non-text Content	A
1.3.1 Info and Relationships	A
1.4.3 Contrast (Minimum)	AA

Automated test results: Accessibility and compliance.

Notes and known caveats

• Symbols such as the Command sign are hidden from assistive technology and replaced by localized names (‘Command’), so screen readers do not announce unknown glyphs.
• Shortcuts supplement, never replace, a visible way to reach the command.
• Manual screen-reader verification (NVDA, JAWS, VoiceOver) is pending.

Behavior

States

Platforms apple and other; sizes sm and md.

State transitions

From	Trigger	To
any	update({ hotkey, platform, size, locale })	new keycaps
any	global configuration change	platform, size, and locale follow the configuration unless set on the instance
any	destroy()	host restored to empty

Accessibility notes

• Screen readers hear “Command S” rather than an unknown glyph on Apple platforms.
• A shortcut should never be the only way to reach a command.
• The e2e axe run covers three themes; manual screen-reader verification is pending.

Responsive behavior

Keycaps in one combination do not wrap; the combination wraps as a unit with surrounding text.

Right-to-left

Key order follows the hotkey string in both directions; shortcuts are not mirrored.

Theming

color-text on --aui-kbd-bg is in the contrast gate. Keycaps have a thicker bottom border. Forced-colors mode draws CanvasText borders.

Global configuration

configureAbsoluteUI({ components: { kbd: { platform: 'apple', size: 'sm' } } });

Component configuration

Instance options override global and theme configuration. Configuration changes re-render existing instances.

Icons

None. Modifier and arrow symbols are Unicode characters, not icons.

Security

Key text uses textContent; it is never parsed as HTML. CSP-safe.

Data handling

With platform: 'auto', reads navigator.userAgent on render (the same signal as matchesHotkey). No persistence, network access, or telemetry.

Performance

Constant work per render: one element per key.

Supported data scale

Not data-driven.

Edge cases

• One combination per instance: show a sequence (“G then I”) as one Kbd per step.
• Ctrl+Plus shows the + key; Ctrl++ is rejected.
• On Apple platforms both Mod and Meta show Command, and Ctrl shows Control.
• Safe in renderers that discard nodes without calling destroy(), such as Data Table cells: the configuration subscription holds the instance weakly, so a discarded shortcut is released.

Errors

Code	Category	Cause
KBD_OPTIONS	configuration	Missing hotkey, an empty part ('Ctrl+'), or an unknown platform.
CFG_INVALID_VALUE / CFG_UNKNOWN_OPTION	configuration	Invalid platform, size, or locale configuration.

Invalid options throw before the host is modified; an invalid update() leaves the previous state intact.

Known limitations

• Platform detection with auto uses the user-agent string; set platform when it is known.
• Manual screen-reader verification is pending.

Unsupported scenarios

• Listening for key presses: use matchesHotkey.
• HTML or Node content.