# Kbd > A keyboard key, shown as a small label with a border, or as quiet text inside a field, with a group part for key combinations. - Name: `kbd` - Status: beta - Categories: data, display - File: the install writes `kbd.tsx` to your `ui` alias, `@/components/ui` by default. - npm packages: `class-variance-authority`. The install adds them. - Gallery: https://arbokui.com/components/kbd - Registry item: https://arbokui.com/r/kbd.json ## Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@arbokui=https://arbokui.com/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@arbokui": "https://arbokui.com/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@arbokui` in a public list that Arbokui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @arbokui/theme ``` 3. Add the component: ```bash npx shadcn@latest add @arbokui/kbd ``` ## Use it for - Showing which key to press, in help text, menus, tooltips, and empty states. - Use KbdGroup for a combination, with one Kbd per key and a + between them. - Write the key the way it is printed on the keyboard: Ctrl, Shift, Enter, Esc. - Use size to match the text around it: sm in small print, md beside text-sm, lg beside text-base. - Use emphasis="ghost" for a shortcut hint inside a field, like a search box, where a bordered key would look like a second control. ## Avoid it for - Making a key clickable. A Kbd is a label. Put the action on a Button. - Printing a key beside a button on the page. Teach it in the button's tooltip with TooltipPopup's shortcut prop. - Putting aria-label on a Kbd. A \has no role, so ARIA does not allow a label on it. Use visually hidden text instead. - Showing a shortcut that does not work on the person's platform. Show Ctrl or ⌘ to match their system. - Code or file names. Use \ for those. ## Props - `emphasis`: `"solid" | "ghost"`. Default `"solid"`. solid draws a border and a fill. ghost shows only the text, at the same size. - `size`: `"sm" | "md" | "lg"`. Default `"md"`. Height, width, and text size. Density scales them. - `className`: `string`. Extra classes. Later classes win, so className='rounded-full' replaces the radius. - `Kbd`: `Omit, "color">`. One key. Renders a \. At least as wide as it is tall, so one letter makes a square key. - `KbdGroup`: `Omit, "color">`. Part. Holds the keys of one combination. Renders a \, as HTML asks for key combinations. - `kbdVariants`: `({ emphasis, size }) => string`. The key's classes, for styling another element as a key. ## Accessibility - Renders a native \. Screen readers read its text, so the text must say the key. - Screen readers may read symbols badly or skip them. For ⌘, ⌥, or ⇧, hide the symbol with aria-hidden and add the key name in a span with className='sr-only'. - Never put aria-label on a Kbd. A \ has no role, so ARIA does not allow a label on it, and screen readers may skip it. - Write a + between keys in a KbdGroup, so the text itself says the keys go together. - Not focusable and not interactive. It adds no tab stop. - Solid text is muted-foreground on muted. Ghost text is muted-foreground on what is behind it. The theme tests hold muted-foreground to 4.5:1 on muted, background, card, and popover, in light and dark. ## Examples ### One key in a sentence ```tsx Press Esc to close. ``` ### A key combination ```tsx Ctrl+K ``` ### A symbol key with a name screen readers can read ```tsx ⌘ Command +K ``` ### A quiet hint inside a field ```tsx / ``` ### A shortcut beside a menu action ```tsx Search Ctrl+K ```