Kbd Key
Overview
A 3D keycap that physically depresses when the matching key is pressed.
This input component is intended for interfaces that need a 3D keycap that physically depresses when the matching key is pressed, forms, and search workflows. Its implementation is provided as editable source so the final behavior and styling stay inside your project.
Technologies
Detected package dependencies: framer-motion.
Press ⌘ K on your keyboard — the caps react
Installation
Usage
import { KbdKey, KbdCombo } from "@/components/spectrumui/kbd-key"<KbdKey>K</KbdKey>
<KbdCombo keys="meta+k" onTrigger={() => console.log("open palette")} />API Reference
KbdKey
Renders a single kbd element styled as a keycap. With listen enabled it depresses while the matching real key is held; when onPress is provided the cap is wrapped in a focusable button.
| Prop | Type | Default | Description |
|---|---|---|---|
*children | React.ReactNode | - | Cap legend, e.g. "K", "⌘" or "esc" |
keyName | string | - | Key matched against KeyboardEvent.key, case-insensitively. Friendly names work: "meta", "ctrl", "shift", "alt", "enter", "escape", "space", "up"… Derived from children when it is a plain string; symbol legends like "⌘" need an explicit keyName |
listen | boolean | true | Depress the cap while the real key is held, via a window listener |
onPress | () => void | - | Fires once per press — on a matching keydown or a pointer tap. Also wraps the cap in a button for accessibility |
size | "sm" | "md" | "md" | Visual size of the cap |
className | string | - | Additional classes merged with the default cap styles |
KbdCombo
Renders one KbdKey per key joined by + separators. Each cap listens to its own key; when every key is down at the same time the whole combo pulses once and onTrigger fires.
| Prop | Type | Default | Description |
|---|---|---|---|
*keys | string | - | "+"-separated keys, e.g. "meta+k" or "shift+?". Names map to glyphs: meta → ⌘, shift → ⇧, alt → ⌥, ctrl → ⌃, enter → ↵, space → ␣, escape → esc, arrows → ↑ ↓ ← → |
listen | boolean | true | Depress each cap while its real key is held |
onTrigger | () => void | - | Fires once each time every key in the combo is held down simultaneously |
size | "sm" | "md" | "md" | Visual size of the caps |
className | string | - | Additional classes merged with the combo wrapper styles |
Examples
Arrow cluster
Press your arrow keys — each cap depresses while held
A small combo — hold ⇧ and ? together and it pulses
Use cases
- interfaces that need a 3D keycap that physically depresses when the matching key is pressed
- forms
- search workflows
Features
- Copy-paste source that remains in your repository
- TypeScript source included with the component
- Tailwind CSS classes editable in the component source
- Animation implemented with Motion
- Responsive Tailwind variants present in the source
- Reduced-motion handling present in the source
Accessibility
- The source includes ARIA attributes or roles; preserve them when customizing the component.
- The source includes keyboard event handling; verify it alongside pointer behavior.
- The source checks reduced-motion preferences or includes motion-reduce styles.
- Test focus order, keyboard operation, labels, contrast, and screen-reader output in the final application context.
Customization
- Edit the Tailwind utility classes in the copied source to match your spacing, color, and typography tokens.
- Use the documented className surface for local layout adjustments, then edit the source for structural changes.
- Adjust Motion transitions in the source and keep the reduced-motion behavior aligned with the final interaction.
Related components
Topic guides
See how this component fits into broader interface patterns, implementation decisions, and working examples.
Kbd Key FAQ
Is Kbd Key free to use in commercial projects?
Yes. The public Kbd Key source is available under the Apache License 2.0, including for commercial use, subject to the LICENSE terms.
How do I install Kbd Key?
Run npx shadcn@latest add @spectrumui/kbd-key. The page also exposes the source for manual installation.
Does Kbd Key require Motion?
Yes. Motion usage was detected in the documented source or registry dependencies for Kbd Key.
Does Kbd Key use shadcn/ui or Radix UI?
No shadcn/ui or Radix UI dependency was detected in the documented Kbd Key source.
Can I use Kbd Key in Next.js?
The documented React source is used in this Next.js application. Keep its use client directive when copying it into the App Router. Install the detected dependencies and verify any application-specific data or image configuration.
What accessibility checks should I run for Kbd Key?
The source includes ARIA markup, keyboard handlers, reduced-motion handling. Test the finished interface with keyboard and screen-reader workflows.