kbd

Used to display textual user input from keyboard.

Note: You might wonder why we don't use the CommandShortcut component from the command module. The reason is that we want to give you the flexibility to use the kbd component in any context, not just within a command. Additionally, the CommandShortcut component is specifically designed to represent a keyboard shortcut associated with a command, not a plain HTML element. As a result, it has a different API and does not require certain props like keys or onKeyPress.

Philosophy

Keyboard shortcuts deserve visual prominence. The Kbd component renders key combinations with consistent styling, making shortcut discovery a natural part of the UI rather than something hidden in documentation. We pair it with @gentleduck/vim for actual key binding - Kbd handles the display, vim handles the logic.

Installation

npx @gentleduck/cli add kbd

npx @gentleduck/cli add kbd

Usage

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

<Kbd>Ctrl</Kbd>

Examples

Group

Use the KbdGroup component to group keyboard keys together.

Button

Use the Kbd component inside a Button component to display a keyboard key inside a button.

You can use the Kbd component inside a Tooltip component to display a tooltip with a keyboard key.

Input Group

You can use the Kbd component inside a InputGroupAddon component to display a keyboard key inside an input group.

RTL Support

Set the direction once with DirectionProvider (or <html dir="rtl">) and the surrounding layout follows it. Kbd and KbdGroup take their direction from their own label, so shortcuts such as Ctrl + S or ⌘K keep their order inside right-to-left text.

Motion

Alpha: Motion Compositions

Motion components work standalone, but some compositions may behave unexpectedly: this is still under active development. If you find a broken composition, please file an issue.

Use MotionKbd for a staggered scaleIn entrance (fade, scale, and blur) with a bouncy spring transition on keyboard shortcuts, powered by motion.

Requires the motion package. Use MotionKbd instead of Kbd. Pass index for stagger order.

API Reference

Kbd

Displays an individual keyboard key with consistent styling.

Prop	Type	Default	Description
`dir`	`'ltr' \| 'rtl' \| 'auto'`	`'auto'`	Text direction. Defaults to `auto`, so it follows the key label rather than the page.
`className`	`string`	-	Additional class names for the kbd element
`keys`	`string`	-	Raw key combo string formatted for display via `@gentleduck/vim`'s `formatForDisplay`. Used as a fallback when `children` is not provided.
`children`	`React.ReactNode`	-	Key label text or icon. Takes precedence over `keys` when both are provided.
`...props`	`React.HTMLProps<HTMLElement>`	-	Additional props to spread to the kbd element

KbdGroup

Groups multiple Kbd components together in an inline layout.

Prop	Type	Default	Description
`className`	`string`	-	Additional class names for the group
`children`	`React.ReactNode`	-	`Kbd` elements to group together
`...props`	`React.ComponentPropsWithoutRef<'div'>`	-	Additional props to spread to the group element (renders as a `kbd`)

MotionKbd

Same props as Kbd plus an optional index prop for stagger delay (30ms per index). Adds a scaleIn entrance (fade, scale, and blur) with a bouncy spring transition. Requires the motion package.