Skip to content
garn

Kbd

Displays a keyboard key or shortcut as a keycap.

Stablev0.4.2added in v0.1.0@garn/ui/kbd
On this page

Default

A single keycap.

K

Appearance

Fill treatment: `default` carries a muted fill; `ghost` is transparent for quieter inline hints.

Default

Ghost

Sizing

Keycap height 20/24/28px — identity geometry (density-immune).

Installation

garn is copy-in — the garn CLI writes this component's source into your project, so you own and can edit it. It resolves any base files and installs the npm dependencies below for you.

terminal
npx garn-ui add kbd
First time? Set up garn in your project
Registry
kbd
Deps
class-variance-authority
Registry deps
utils

Import

import { KbdGroup } from "@garn/ui/kbd";

Anatomy

The parts this component is built from — compose them to assemble it.

KbdGroup[data-slot="kbd-group"]

Lays out a sequence of keys (⌘ + K, or “g then i”); pass the separators (+ / then) as children.

Props

The component's public props and their types.

appearance
Description
No description.
Type
"default" | "ghost"
Default
default
size
Description
No description.
Type
"lg" | "md" | "sm"
Default
md

Plus 280 inherited native <kbd> attributes.

Styling

Target these data-slots and states, and remap these tokens, to restyle without forking the component.

[data-slot="kbd"]
PropertyTokenTier
background--garn-mutedsemantic · identity
foreground--garn-muted-foregroundsemantic · identity

When to use

Show a keyboard key or shortcut inline — menus, tooltips, command hints, docs.

Reach for something else when

  • To capture key presses or for editable input — Kbd is display-only.

Overview

Kbd renders a keyboard key or shortcut inline as a small keycap — in menus, tooltips, command hints, and docs. appearance is default (muted fill) or ghost (transparent for quieter hints), and a KbdGroup chains keys into a combo (⌘ K). It's display-only: it shows a shortcut, it doesn't capture or bind one — wire the actual key handler separately.

Guidelines

Use Kbd to display a shortcut, never to capture input. It's a visual keycap, not an input — pair it with a real keyboard handler (and a DropdownMenuShortcut is also display-only). For editable text use Input.

Show the platform's real keys. Render ⌘ on macOS and Ctrl on Windows/Linux rather than a single hardcoded combo, and use the conventional glyphs (⌘ ⇧ ⌥ ⏎). Group multi-key combos with KbdGroup so they read as one shortcut.

Keep it quiet and legible. Use ghost inside dense menus and tooltips where a filled keycap would shout; reserve default for docs and standalone hints. Don't pile shortcut hints onto every control — surface them where discovery actually helps.

Best practices

Do
  • Use KbdGroup for multi-key shortcuts and pass the separator as children.
  • Keep a keycap to one or two glyphs.
Don't
  • Don't put long text in a keycap.
  • Don't rely on Kbd alone to convey an actionable shortcut to assistive tech.

Content guidelines

  • Use the platform's real glyphs (⌘ ⌥ ⇧ ⏎) rather than spelling out the keys.
  • Keep each keycap to a single key; compose multi-key shortcuts with KbdGroup.
  • Match the casing users see on their keyboard (“Esc”, “Tab”, “⌘K”).

Troubleshooting

Separators in a shortcut look wrong or are missing.

Cause. KbdGroup doesn't insert separators; consumers control phrasing.

Fix. Pass the “+” or “then” between <Kbd> children yourself.

Accessibility

  • Renders native <kbd> (phrasing content); it is display-only.
  • Convey the actionable shortcut where it matters (e.g. in the menu item's accessible name) — Kbd alone isn't announced as a shortcut.