Skip to content

Keyboard key

Preview Available in release assets

Skin the native <kbd> element as a compact keycap for keyboard shortcut guidance without redefining its semantics or content model.

Keyboard key primary example

Show code
<p>Press <kbd class="thin-kbd">
<kbd class="thin-kbd">Ctrl</kbd>
<kbd class="thin-kbd">K</kbd>
</kbd> to open the command palette, or <kbd class="thin-kbd">Esc</kbd> to dismiss it.</p>

Each authored example uses the production assets and includes copyable markup.

Single native key

A native kbd remains text, without a click or key binding. The application decides whether a documented shortcut exists.

Show code
<p style="overflow-wrap: anywhere">Use <kbd class="thin-kbd" >Esc</kbd> to describe the Escape key.</p>

Nested modifier chord

Nested native key labels express a chord. This example documents the notation and installs no shortcut.

Show code
<p style="overflow-wrap: anywhere">An application may document <kbd class="thin-kbd" dir="ltr">
<kbd class="thin-kbd" >Ctrl</kbd>+<kbd class="thin-kbd" >K</kbd>
</kbd> as its command shortcut.</p>

Small key label

The documented size attribute changes the visual keycap while preserving its native meaning.

Show code
<p><kbd class="thin-kbd" data-size="small">Esc</kbd></p>

Large key label

Larger notation remains ordinary readable text.

Show code
<p><kbd class="thin-kbd" data-size="large">Esc</kbd></p>

Anatomy

  • Native kbd element with class="thin-kbd"
  • Author-supplied key label (letters, symbols, or localized text)
  • Optional nested kbd children forming a chord
  • Optional data-size attribute for small or large surfaces

Variants and sizes

  • Single key — shown above
  • Chord of nested keys — shown above
  • Small (data-size="small") — shown above
  • Large (data-size="large") — shown above
  • Modifier plus letter chord — shown above

Rendered fixtures exercise authored content and constrained layouts with the same production assets.

Inline text and punctuation

Surrounding words, commas and periods stay in the sentence. Keycaps are not controls or badges for unrelated values.

Show code
<p style="overflow-wrap: anywhere">Choose <kbd class="thin-kbd" >S</kbd>, then <kbd class="thin-kbd" >Enter</kbd>. To cancel, use <kbd class="thin-kbd" >Esc</kbd>.</p>

Nested chord and localized key names

Long translated key labels wrap inside a constrained text measure rather than widening the page.

Show code
<section lang="de" style="max-inline-size: 18rem; overflow-wrap: anywhere">
  <p>Tastenkombination: <kbd class="thin-kbd" dir="ltr">
  <kbd class="thin-kbd" >Ctrl</kbd>+<kbd class="thin-kbd" >K</kbd>
</kbd>.</p>
<p>Tastenname: <kbd class="thin-kbd" >Rücktaste beziehungsweise Rückschritttaste</kbd>.</p>
</section>

Shortcut notation in RTL prose

The surrounding prose is RTL; the authored Latin-key chord retains its reading order with dir=ltr.

Show code
<p dir="rtl" lang="ar" style="overflow-wrap: anywhere">اختصار لوحة المفاتيح: <kbd class="thin-kbd" dir="ltr">
<kbd class="thin-kbd" >Ctrl</kbd>+<kbd class="thin-kbd" >K</kbd>
</kbd>.</p>

System colors and enlarged notation

Inspect system forced colors and 200%/400% zoom. The key name remains content; automated text enlargement is separate from human OS/AT review.

Show code
<p style="overflow-wrap: anywhere">A larger label remains readable: <kbd class="thin-kbd" >Page Down</kbd>.</p>
  • Inline inside body text — shown above
  • Nested chord — shown above
  • Long localized labels — shown above
  • Right-to-left reading direction — shown above
  • Adjacent to punctuation — shown above
  • Forced colors — shown above
  • 200% and 400% zoom — shown above

Interaction and keyboard behavior

The kbd element is presentational text. Any keyboard shortcut is bound to the surrounding control or document, never to the keycap itself.

Accessibility

Keep the visible text equal to the key the reader must press so screen readers announce the same characters. Do not replace descriptive text with an icon-only keycap, and do not use kbd for editable UI text or numeric measurements. Nest kbd elements to express chords so the surrounding punctuation and separators remain part of the sentence.

Contract
NATIVE
Basis
Native <kbd> and non-focusable separator; a focusable separator must move to the experimental splitter contract
Evidence
  • tests/unit/library/spinner-kbd-separator.test.ts

API

Use kbd.thin-kbd for a keycap. Nest additional kbd.thin-kbd children inside a wrapping kbd.thin-kbd to represent a chord. Adjust density with data-size="small" or data-size="large"; color inherits from the surrounding text.

Behavior tier: native

Structured host, property, and example tables are not authored for this item yet. Use the summary above and the primary example.

Fallback

Without Thin-Sky CSS the kbd element retains its native monospace styling and remains readable as inline text.

Assets and dependencies

  • /components.css

Dependencies: None

Source: packages/ui/src/items/kbd/style.ts