Kbd

Display-only key-cap chip for shortcut hints.

Renders a key combo from the shortcut grammar (`mod+k`, `?, mod+/`) as nested `<kbd>` key caps — correct per-platform glyphs (⌘K on Apple, Ctrl+K elsewhere), mono font, zero radius. Purely visual: it registers nothing and handles no events. Register the actual binding through `shortcuts.add()` / the `shortcut()` attachment, and use `<Kbd>` for the hint in buttons, menus, tooltips, and help overlays.

Demo

live · storybook Open in Storybook

Demo loads from https://dssoca-storybook.vercel.app/. Run pnpm storybook for it to render locally.

Usage

svelte

<script>
  import { Kbd, ariaKeyshortcuts } from 'dssoca';
</script>

<button aria-keyshortcuts={ariaKeyshortcuts('mod+k')}>
  Search <Kbd keys="mod+k" />
</button>

<Kbd keys="?, mod+/" />
<Kbd keys="mod+shift+k" format="label" />
<Kbd>F12</Kbd>

Kbd is purely visual — assistive tech gets the combo as one full-word name (`aria-label="Command K"` via `role="img"` in glyph format), but the chip alone is not an affordance: never show a key without explanatory text next to it ("Search ⌘K", not a bare chip). The real binding belongs on the owning control — register it through the shortcut registry and set `aria-keyshortcuts` there with the `ariaKeyshortcuts()` helper so AT users learn the shortcut from the control itself. **Hidden on touch devices by default** (`hideOnMobile`): a key cap is noise where the only input is a finger, so on `(hover: none) and (pointer: coarse)` viewports the chip is `display: none` (out of the a11y tree too). That is a capability query, not a width — a narrow desktop window keeps its hints. Opt out with `hideOnMobile={false}` where the chip is the subject rather than a hint (ShortcutsHelp does this for its rows); the surrounding text is yours to hide ("Enter to send" should not degrade to "to send"). Plain HTML: `.ss-kbd` hides the same way, and `data-hide-on-mobile="false"` on the root opts out.

Guide: Making your site keyboard-friendly.

HTML

CSS only — static markup The exact markup the component renders, generated at build time. Use it with dssoca/vanilla.css — see Plain HTML & CSS.

html

<kbd class="ss-kbd" role="img" aria-label="Ctrl K">
  <kbd class="key">Ctrl</kbd>
  <span class="sep" aria-hidden="true">+</span>
  <kbd class="key">K</kbd>
</kbd>

Rendered for the platform at build time; the Svelte component adapts to the visitor's OS.

Props

Prop	Type	Default	Description
`keys`	`string`	—	Combo in the shortcut grammar (`mod+k`, `?, mod+/`). `mod` renders per platform; comma alternatives are joined by a muted "or". Malformed input throws (same parser as registration).
`format`	`'glyph' \| 'label'`	`'glyph'`	glyph = ⌘⇧↵/arrow symbols on Apple (words elsewhere); label = always full words. Glyph roots carry a full-word `aria-label` (⌘ reads poorly in AT).
`platform`	`'apple' \| 'other'`	—	Override platform auto-detection. Defaults to `'other'` on the server and first client render, corrected in an effect (no hydration mismatch); SSR apps can pass it explicitly for a stable first paint.
`size`	`'sm' \| 'md' \| 'lg'`	—	Per-instance size override; inherits the ancestor `data-size-variant` when unset.
`hideOnMobile`	`boolean`	`true`	Hide the chip on devices without a keyboard — a capability query, `(hover: none) and (pointer: coarse)` (phones, tablets), not a width. Pass `false` where the chip is the content (a shortcuts list, a keyboard guide); it then renders `data-hide-on-mobile="false"` on the root.
`children`	`Snippet`	—	Raw-content escape hatch for keys the grammar cannot express (`<Kbd>F12</Kbd>`). Ignored when `keys` is set.