Shortcut

Playground

Installation

pnpm add @tessinaui/ui

Usage

import { Key, Shortcut } from "@tessinaui/ui";

{/* Single key */}
<Key>Esc</Key>

{/* Shorthand — keys array */}
<Shortcut keys={["Ctrl", "K"]} />
<Shortcut keys={["Cmd", "Shift", "P"]} />

{/* "mod" — ⌘ on Apple keyboards, Ctrl everywhere else */}
<Shortcut keys={["mod", "K"]} />

{/* Apple symbols, on Apple platforms */}
<Shortcut keys={["mod", "shift", "p"]} glyphs />

{/* Force a platform — previews, tests, server-resolved rendering */}
<Shortcut keys={["mod", "K"]} glyphs platform="mac" />

{/* On a colored surface */}
<Surface background="primary">
  <Shortcut keys={["mod", "K"]} tone="on-color" />
</Surface>

{/* Compound — children for custom compositions */}
<Shortcut>
  <Key>Ctrl</Key>
  <Key>K</Key>
</Shortcut>

{/* Mixed rounded per-key */}
<Shortcut>
  <Key>Cmd</Key>
  <Key rounded="full">⌘</Key>
</Shortcut>

{/* Rounded variant */}
<Shortcut keys={["Ctrl", "S"]} rounded="full" />

{/* Custom separator */}
<Shortcut keys={["Ctrl", "K"]} separator="then" />

{/* Size */}
<Shortcut keys={["Ctrl", "S"]} size="lg" />

{/* RTL */}
<Shortcut keys={["Ctrl", "Z"]} dir="rtl" />

Examples

Default

A keyboard combination rendered from the keys array with auto-inserted separators.

Single Key

The standalone Key component for individual keys like Esc or Enter.

Sizes

Five sizes — xs, sm, md, lg, and xl.

Rounded

Border radius variants — none, sm, md, lg, and full.

Separators

Customize the character shown between keys with the separator prop.

Compound

Compose individual Key children for per-key control, like mixing rounded styles.

Glyphs

glyphs swaps the words for Apple's symbols on Apple platforms. Windows and Linux keep the words — they have no glyph convention to follow.

Platform

"mod" is the platform's primary modifier: ⌘ on an Apple keyboard, Ctrl everywhere else. platform forces the answer when you need a deterministic one.

On color

tone="on-color" puts keycaps on a colored surface. Inside a <Surface> it is inherited, so nested shortcuts adapt on their own.

RTL

dir="rtl" mirrors the key order for right-to-left layouts.

In a button

A hint inside the control it belongs to. It sits in trailingIcon, which the button renders aria-hidden, and the shortcut is announced by aria-keyshortcuts on the button instead — otherwise a screen reader reads "Accept Enter" as though the key were part of the label.

In a tooltip

The familiar pattern: hover a control, get one line naming it plus the keys that trigger it.

It composes HoverCard rather than Tooltip, because Tooltip is a static card — it has content slots but no trigger, so it cannot appear on hover. Three overrides turn a card into a tooltip: w-auto max-w-none so the popup shrink-wraps its line, whitespace-nowrap to keep it to one line, and shorter open/close delays.

If you want the static card instead, Tooltip takes a shortcuts array directly and scales the caps against the card — an lg card gets md caps, an sm card gets xs — so nothing needs composing by hand there.

In a search field

Search accepts showShortcut, which puts a ⌘K cap in the field, swaps it for Esc once there is a query, and binds the global focus listener to match.

API Reference

Key props

All native <kbd> HTML attributes are forwarded.

The exported keyVariants gives access to the same class map for one-off compositions.

Shortcut props

children takes precedence over keys when both are provided. Native <span> attributes are forwarded; dir is re-typed to the two values above.

Key names

Names are matched case-insensitively, and common aliases are accepted. Anything unrecognised renders exactly as written, so app-specific keys still work.

The symbol column applies under glyphs; otherwise the word is used. escape and space have no symbol on purpose — ⎋ reads to almost nobody.

Modifiers render in the order you write them. The convention worth following is Apple's: ⌃ ⌥ ⇧ ⌘, modifiers before the key.

One key, one cap

Every key gets its own keycap, and single-key caps are uniform squares — a ⌘ cap, a C cap and a ⌫ cap are always the same size. Never put a whole run in one cap (<Key>⌘C</Key> as a single chip); that is how a wide ⌘C chip ends up next to a small lone ⌫. The menu shortcut wrappers split their strings automatically via the exported splitKeyRun("⌘⇧S") → ["⌘", "⇧", "S"]; use it anywhere else a combined string arrives.

Accessibility

• Each keycap carries its own accessible name. <kbd> is a generic role, which forbids aria-label, so the name is real text: the visible form is aria-hidden and an sr-only twin alongside it is what gets announced. A cap reading Ctrl announces "Control"; ⌘ announces "Command".

• Symbols you pass yourself are named too, including mixed runs — <Key>⌘S</Key> announces "Command S" rather than a stray character.

• Separators are aria-hidden; a shortcut reads as its keys, in order.

• Shortcut binds nothing. It is a hint. Put the binding on the control and declare it with aria-keyshortcuts, whose syntax is its own (Meta+K, space-separated for alternatives):

  <button aria-keyshortcuts="Meta+K" onClick={open}>
    Search
    <Shortcut keys={["mod", "k"]} glyphs aria-hidden />
  </button>

• When the hint repeats something already announced — a menu item's own shortcut, a search field's placeholder — mark the hint aria-hidden so it is not read twice.

• Not interactive: it takes no focus and has no pointer target, so WCAG 2.5.5's 44px minimum does not apply. The size scale follows the text it sits beside.