Kbd

Install

pnpm dlx shadcn@latest add @vegastack/kbd

Usage

import { Kbd, KbdGroup } from '@/components/ui/kbd';

// Single key
<Kbd>⌘</Kbd>

// A combo as an array — each token is its own chip
<Kbd keys={['⌘', 'K']} />;

Anatomy

Kbd is a compound component. Every exported part, with the data-slot it renders (generated from the canonical source):

Examples

Anatomy

Kbd renders a single <kbd> chip, or — when given a keys array — a row of chips wrapped in a KbdGroup. Compose KbdGroup yourself to mix in non-key content.

<KbdGroup>
  <Kbd>⌘</Kbd>
  <Kbd>K</Kbd>
</KbdGroup>

Combos

Pass a keys array to render a shortcut, or compose individual Kbd chips inside a KbdGroup. Write tokens as mac glyphs; os decides how they render. The default is os="other" (words), so pass os="mac" — or the resolved platform — for the glyphs.

Sizes

xs, sm, and md — sized to sit inline with text, menus, and tooltips. All three use one type role, text-code-sm; md previously reached the same 12px through text-sm, the same pixel size named twice.

Platform Labels

Kbd is server-safe and deterministic: it reads no navigator and therefore never guesses the platform. Resolving the platform is the caller's job — run usePlatform() and pass the answer down. os defaults to "other", the same fallback usePlatform reports before hydration, so an unwired chip shows a word every reader understands rather than shipping ⌘ to a Windows majority.

The rewrite applies whether you pass a keys array or a single string child (⌘ → Ctrl, ⇧ → Shift, ⌥ → Alt, ⌃ → Ctrl, ⏎/↵ → Enter, ⌫ → Bksp). On mac the glyph is rendered visually with an sr-only spoken name beside it, because a screen reader announces ⌘ as "place of interest sign" or skips it entirely.

// The wiring every caller should use
const { os } = usePlatform();
<Kbd keys={["⌘", "K"]} os={os === "mac" ? "mac" : "other"} />;

<Kbd os="mac" keys={['⌘', 'K']} />   {/* ⌘ K */}
<Kbd os="other" keys={['⌘', 'K']} /> {/* Ctrl K (the default) */}

// Single string children are rewritten too
<Kbd os="other">⌘</Kbd>             {/* Ctrl */}

Playground

Change the size and platform to watch the ⌘ glyph swap to Ctrl, then copy the generated JSX.

<Kbd keys={['⌘', 'K']} />

API Reference

Kbd

KbdGroup

The kbdVariants CVA helper is also exported for advanced styling — call kbdVariants({ size }) to reuse the chip classes (the single size axis: xs | sm | md) on a custom element.

Accessibility

• Renders a native, non-interactive <kbd> element — the semantic element for keyboard input, so assistive tech announces it as such.
• The chip is a label, never a control: it does not receive focus and carries no tabindex. Wire the actual shortcut up on the relevant control (e.g. a button or a menu item).
• Modifier glyphs are rewritten to readable words on non-mac platforms, so a shortcut is never announced as an unfamiliar symbol. On mac the glyph is aria-hidden and an sr-only word (Command, Option, …) carries the accessible name.
• Kbd is the only key chip in the system: TooltipKbd renders it rather than restyling a second <kbd>, so a shortcut hint reads identically wherever it appears.

Do / Don't