Kbd

Display keyboard keys and shortcuts as soft keycaps that read the user's platform

Primitive

Kbd renders a keyboard key as a soft keycap: a translucent fill with a one-pixel lip, both taken from the color of the text around it, so it reads on the page, in a tooltip and on a primary button without a variant per surface. Pass keys to draw a whole shortcut on one cap, and named keys like mod and shift become the right legend for the user's platform: ⌘Command plus K on a Mac, Ctrl+K everywhere else.

Preview

Open command palette: ⌘Command plus K
Save document: ⌘Command plus S
Find and replace: ⌘Command plus ⌥Option plus F
Toggle sidebar: ⌘Command plus B

import { Kbd } from "@/components/ui/cubby-ui/kbd";
 
const SHORTCUTS = [
  { label: "Open command palette", keys: ["mod", "k"] },
  { label: "Save document", keys: ["mod", "s"] },
  { label: "Find and replace", keys: ["mod", "alt", "f"] },

Installation

npxnpx shadcn@latest add @cubby-ui/kbd

Usage


import { Kbd, KbdGroup } from "@/components/ui/cubby-ui/kbd"


<Kbd keys={["mod", "k"]} />
 
<KbdGroup>
  <Kbd>G</Kbd>
  <span>then</span>
  <Kbd>D</Kbd>
</KbdGroup>

Composition

KbdGroup
└── Kbd

Examples

Single Keys

Put the legend in children for a key you spell out yourself.

⌘KEscTab↵

import { Kbd } from "@/components/ui/cubby-ui/kbd";
 
export default function KbdSingleKeys() {
  return (
    <div className="flex items-center gap-2">
      <Kbd>⌘</Kbd>

Shortcuts

Use keys to draw a shortcut on one cap. Mac legends sit side by side; elsewhere they're joined with +. Set separator to change that.

⌘Command plus K⌘Command plus ⇧Shift plus P⌥Option plus ⇥Tab⌘Command plus /K

import { Kbd } from "@/components/ui/cubby-ui/kbd";
 
export default function KbdKeyCombinationsWithProps() {
  return (
    <div className="flex flex-wrap items-center gap-4">
      <Kbd keys={["mod", "k"]} />

Named Keys

Named keys are case-insensitive and turn into the platform's legend. Symbols carry a hidden label, so a screen reader says "Command" rather than the glyph's name. Any other single character is uppercased; longer names are drawn as written.

mod⌘Command

ctrl⌃Control

alt⌥Option

shift⇧Shift

enter↵Return

backspace⌫Delete

tab⇥Tab

escEsc

spaceSpace

up↑Up arrow

down↓Down arrow

left←Left arrow

right→Right arrow

import { Kbd } from "@/components/ui/cubby-ui/kbd";
 
const NAMED_KEYS = [
  "mod",
  "ctrl",
  "alt",

Key	Mac	Windows and Linux
`mod` (`cmd`, `command`)	⌘	Ctrl
`meta`	⌘	Win
`ctrl` (`control`)	⌃	Ctrl
`alt` (`option`)	⌥	Alt
`shift`	⇧	Shift
`enter` (`return`)	↵	Enter
`backspace`	⌫	Backspace
`delete`	⌦	Del
`tab`	⇥	Tab
`capslock`	⇪	Caps Lock
`esc` (`escape`), `space`	Esc, Space	Esc, Space
`up`, `down`, `left`, `right`	↑ ↓ ← →	↑ ↓ ← →

Platform

platform defaults to "auto", which reads the user's OS. Set "mac" or "windows" to pin one. A key rendered on the server shows Mac legends until it hydrates; keys in menus, dialogs and tooltips mount on the client and are right from their first frame.

Auto⌘Command plus ⇧Shift plus PMac⌘Command plus ⇧Shift plus PWindowsCtrl plus +Shift plus +P

import { Kbd } from "@/components/ui/cubby-ui/kbd";
 
export default function KbdPlatformDetection() {
  return (
    <div className="grid grid-cols-[auto_auto] items-center gap-x-4 gap-y-3 text-sm">
      <span className="text-muted-foreground">Auto</span>

Group

Wrap several Kbd in KbdGroup to show a shortcut as separate caps, or a sequence with words between them. The group is an outer kbd, the HTML way to mark up a combination. Put text like + or "then" in a span and it stays quiet.

⌘Command⇧ShiftPCtrl+Alt+DelGthenD

import { Kbd, KbdGroup } from "@/components/ui/cubby-ui/kbd";
 
export default function KbdGroupExample() {
  return (
    <div className="flex flex-col items-start gap-3">
      <KbdGroup>

Variants

default is the filled keycap. outline takes the outline Button's fill and edge, for a key that sits on a muted plate; it keeps that surface's colors, so use default on a solid fill. ghost is the legend alone, for menus and dense rows.

⌘Command plus K⌘Command plus K⌘Command plus K

import { Kbd } from "@/components/ui/cubby-ui/kbd";
 
export default function KbdVariants() {
  return (
    <div className="flex items-center gap-4">
      <Kbd variant="default" keys={["mod", "k"]} />

Sizes

⌘Command plus K⌘Command plus K⌘Command plus K

import { Kbd } from "@/components/ui/cubby-ui/kbd";
 
export default function KbdSizeVariants() {
  return (
    <div className="flex items-center gap-4">
      <Kbd size="sm" keys={["mod", "k"]} />

Size	Height	Use
`sm`	18px	Tooltips, menu rows, command footers.
`md`	20px	Running text and shortcut lists.
`lg`	24px	Keyboards and anything you want to show.

In Text

Kbd sits on the text baseline, so it drops into a sentence without nudging the line.

Press ⌘Command plus K to open the command palette.

Use ↑Up arrow↓Down arrow to move and ↵Return to pick.

Press Esc to close any dialog.

import { Kbd, KbdGroup } from "@/components/ui/cubby-ui/kbd";
 
export default function KbdInContext() {
  return (
    <div className="max-w-sm space-y-2 text-sm">
      <p>

The fill is mixed from the current ink, so the same key reads in the default tooltip and the inverse one.

import { HugeiconsIcon } from "@hugeicons/react";
import { Copy01Icon, Scissor01Icon } from "@hugeicons/core-free-icons";
import { Button } from "@/components/ui/cubby-ui/button";
import { Kbd } from "@/components/ui/cubby-ui/kbd";
import {
  Tooltip,

In a Button

Pass the key as trailingIcon so it sits apart from the label. It wears the button's text color and takes a stronger fill, so it reads on a solid fill with no override. Hide the key with aria-hidden and name the shortcut with aria-keyshortcuts, so the button is still announced as "Save".

import { Button } from "@/components/ui/cubby-ui/button";
import { Kbd } from "@/components/ui/cubby-ui/kbd";
 
// The key is decoration here: `aria-keyshortcuts` names the shortcut, so the
// button is still announced as just "Save".
export default function KbdInButton() {

Pressed

pressed pushes the key down a pixel, drops its lip and darkens its fill. Type to try it.

QWERTYUIOP

ASDFGHJKL

ZXCVBNM

⇧Shift⌃Control⌥Option⌘CommandSpace

"use client";
 
import * as React from "react";
import { Kbd } from "@/components/ui/cubby-ui/kbd";
 
const ROWS = [

Kbd