Kbd

A keyboard key indicator for displaying shortcuts and key bindings.

⌘K

import { Kbd } from "@/components/kbd";

export default function KbdPreview() {
  return (
    <Kbd.Group>
      <Kbd>⌘</Kbd>
      <Kbd>K</Kbd>
    </Kbd.Group>
  );
}

Dependencies

Slot

Source Code

import type { VariantProps } from "cva";

import { Slot } from "@/components/slot";
import { cn, cva } from "@/lib/utils/classnames";

const kbdStyle = cva({
  base: [
    "inline-flex h-(--kbd-height) min-w-(--kbd-height) shrink-0 items-center justify-center",
    "rounded-md border border-border bg-background-secondary",
    "font-mono text-foreground leading-none",
    // 2px hard shadow visually weighs the bottom; lift 1px to optically center
    // against surrounding text.
    "-translate-y-px shadow-[0_2px_0_0_var(--color-border)]",
  ],
  variants: {
    size: {
      sm: "px-1 text-2xs [--kbd-height:--spacing(4)]",
      md: "px-1.5 text-xs [--kbd-height:--spacing(5)]",
      lg: "px-2 text-sm [--kbd-height:--spacing(6)]",
    },
  },
  defaultVariants: {
    size: "md",
  },
});

interface KbdProps extends React.ComponentPropsWithRef<"kbd"> {
  size?: VariantProps<typeof kbdStyle>["size"];
  asChild?: boolean;
}

const Kbd = ({ ref, children, size = "md", className, asChild, ...rest }: KbdProps) => {
  const Comp = asChild ? Slot : "kbd";

  return (
    <Comp ref={ref} className={cn(kbdStyle({ size }), className)} {...rest}>
      {children}
    </Comp>
  );
};

const KbdGroup = ({ className, children, ...rest }: React.ComponentPropsWithRef<"span">) => {
  return (
    <span className={cn("inline-flex items-center gap-1 align-middle", className)} {...rest}>
      {children}
    </span>
  );
};

const CompoundKbd = Object.assign(Kbd, {
  Group: KbdGroup,
});

export { CompoundKbd as Kbd };

Anatomy

          <Kbd />

<Kbd.Group>
  <Kbd />
  <Kbd />
</Kbd.Group>

API Reference

Kbd

Extends the kbd element.

Prop	Default	Type
`size`	`"md"`	`"sm""md""lg"`
`asChild`	-	`boolean`

Kbd.Group

Extends the span element. Wraps multiple Kbds with consistent spacing and alignment so they read as a single shortcut.

Examples

Sizes

⌘⌘⌘

import { Kbd } from "@/components/kbd";

export default function KbdSizesPreview() {
  return (
    <div className="flex items-center gap-4">
      <Kbd size="sm">⌘</Kbd>
      <Kbd size="md">⌘</Kbd>
      <Kbd size="lg">⌘</Kbd>
    </div>
  );
}

Inline in text

Press ⇧⌘P to open the command palette, or Esc to close it.

import { Kbd } from "@/components/kbd";

export default function KbdInlinePreview() {
  return (
    <p className="text-foreground-secondary text-sm">
      Press{" "}
      <Kbd.Group>
        <Kbd>⇧</Kbd>
        <Kbd>⌘</Kbd>
        <Kbd>P</Kbd>
      </Kbd.Group>{" "}
      to open the command palette, or <Kbd>Esc</Kbd> to close it.
    </p>
  );
}

OS-aware shortcuts

Kbd is a presentational element — it renders whatever you put inside. For OS-aware rendering (⌘ on macOS, Ctrl elsewhere), detect the platform once at the top of your tree and pass the right symbol:

          const isMac = typeof navigator !== "undefined" && navigator.platform.toLowerCase().includes("mac");
const modKey = isMac ? "⌘" : "Ctrl";

<Kbd.Group>
  <Kbd>{modKey}</Kbd>
  <Kbd>K</Kbd>
</Kbd.Group>;

Common Mac glyphs: ⌘ Command, ⌥ Option, ⌃ Control, ⇧ Shift, ⏎ Return, ⌫ Delete, ⎋ Escape, ⇥ Tab.

Best Practices

Usage:
- Wrap multi-key shortcuts in Kbd.Group so spacing and alignment stay consistent.
- Keep contents to a single key or short label (Esc, Tab) — long words should be regular text.
Accessibility:
- The <kbd> element is read by screen readers as keyboard input. Don’t override the role.
- Provide written context next to the shortcut so it’s discoverable without sight (e.g., “Press ⌘K to search”).

Input

Listbox