import { html } from '@webjsdev/core';
import { kbdClass, kbdGroupClass } from '#components/ui/kbd.ts';
export default function KbdDemo() {
return html`
<div class="flex flex-col items-center gap-4">
<kbd data-slot="kbd-group" role="img" aria-label="Command Shift Option Control" class=${kbdGroupClass()}>
<kbd data-slot="kbd" class=${kbdClass()}>⌘</kbd>
<kbd data-slot="kbd" class=${kbdClass()}>⇧</kbd>
<kbd data-slot="kbd" class=${kbdClass()}>⌥</kbd>
<kbd data-slot="kbd" class=${kbdClass()}>⌃</kbd>
</kbd>
<kbd data-slot="kbd-group" role="img" aria-label="Control plus B" class=${kbdGroupClass()}>
<kbd data-slot="kbd" class=${kbdClass()}>Ctrl</kbd>
<span>+</span>
<kbd data-slot="kbd" class=${kbdClass()}>B</kbd>
</kbd>
</div>
`;
}
View Code
Installation
Copy and paste the following code into your project.
/**
* Kbd: keyboard chord display. Tier-1 class helpers; compose with the
* native `<kbd>` element for correct semantics.
*
* shadcn parity:
* Kbd → kbdClass()
* KbdGroup → kbdGroupClass()
*
* Design tokens used: --muted, --muted-foreground, --background.
*
* A11y (required for accessible output):
* SYMBOL-ONLY KEYS NEED A SPOKEN NAME. A screen reader reads a bare glyph
* however its speech engine happens to handle that codepoint, so a key shown
* as a symbol can be announced as a meaningless character name or skipped
* entirely. Spell the name the way a person says it: `⌘` is "Command", `⇧`
* "Shift", `⌥` "Option", `⌃` "Control", `⏎` "Enter", `⌫` "Backspace", `␣`
* "Space", `⎋` "Escape", and the arrows are "Up arrow" and friends. A key
* already spelled in words ("Shift", "K") reads correctly and needs nothing.
* DO NOT put `aria-label` on the `<kbd>` itself. `<kbd>` maps to
* `role=generic`, where a name is prohibited and browsers ignore it, so it
* would silently do nothing. Supply the name as TEXT instead: hide the glyph
* with `aria-hidden="true"` and put the spoken form in a visually-hidden
* sibling (`sr-only`), which every screen reader reads.
* NAME THE CHORD, not just the keys, since three `<kbd>` elements are
* otherwise announced as three separate things with no hint they are pressed
* together. Wrap the group in an element with `role="img"` and an
* `aria-label` of the whole chord: `role="img"` both SUPPORTS a name (unlike
* generic) and makes its children presentational, so the chord is announced
* once as one thing. Do not use `role="group"` + `aria-hidden` children for
* this: that leaves the group with nothing to announce.
* Keep the native `<kbd>` element. The class is styling only; `<kbd>` is what
* carries the "this is keyboard input" semantic.
* `<kbd>` DOCUMENTS a shortcut, it does not create one. If the shortcut is
* real, it also needs a keyboard handler, must not clash with an assistive-tech
* or browser binding, and per WCAG 2.1.4 a single-character shortcut has to be
* remappable or disableable.
*
* @example
* ```html
* <!-- A symbol key: hide the glyph, supply the spoken form as text. An
* aria-label on the <kbd> itself would be ignored (role=generic). -->
* <kbd class=${kbdClass()} aria-hidden="true">⌘</kbd><span class="sr-only">Command</span>
*
* <!-- A spelled-out key needs nothing. -->
* <kbd class=${kbdClass()}>K</kbd>
*
* <!-- A chord, announced once as one thing. role="img" supports a name AND
* makes its children presentational, so the glyphs are not read twice. -->
* <div class=${kbdGroupClass()} role="img" aria-label="Command Shift P">
* <kbd class=${kbdClass()}>⌘</kbd>
* <kbd class=${kbdClass()}>Shift</kbd>
* <kbd class=${kbdClass()}>P</kbd>
* </div>
* ```
*/
export const kbdClass = (): string =>
"h-5 w-fit min-w-5 gap-1 rounded-sm bg-muted px-1 font-sans text-xs font-medium text-muted-foreground [&_svg:not([class*='size-'])]:size-3 [[data-slot=tooltip-content]_&]:bg-background/20 [[data-slot=tooltip-content]_&]:text-background dark:[[data-slot=tooltip-content]_&]:bg-background/10 pointer-events-none inline-flex items-center justify-center select-none";
export const kbdGroupClass = (): string => 'gap-1 inline-flex items-center';
Update the import paths to match your project setup.
Usage
import { kbdClass, kbdGroupClass } from '#components/ui/kbd.ts';
<kbd data-slot="kbd" class=${kbdClass()}>Ctrl</kbd>
Composition
Use the following composition to build kbdClass and kbdGroupClass:
kbdClass
kbdGroupClass
├── kbdClass
└── kbdClass
Group
Use kbdGroupClass() to group keyboard keys together.
Use Ctrl + B Ctrl + K to open the command palette
import { html } from '@webjsdev/core';
import { kbdClass, kbdGroupClass } from '#components/ui/kbd.ts';
export default function KbdGroupExample() {
return html`
<div class="flex flex-col items-center gap-4">
<p class="text-sm text-muted-foreground">
Use${' '}
<kbd data-slot="kbd-group" class=${kbdGroupClass()}>
<kbd data-slot="kbd" class=${kbdClass()}>Ctrl + B</kbd>
<kbd data-slot="kbd" class=${kbdClass()}>Ctrl + K</kbd>
</kbd>${' '}
to open the command palette
</p>
</div>
`;
}
View Code
Button
Put a kbdClass() key inside a button to display a keyboard key inside the button.
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import { kbdClass } from '#components/ui/kbd.ts';
export default function KbdButton() {
return html`
<button type="button" data-slot="button" data-variant="outline" data-size="default" class=${buttonClass({ variant: 'outline' })}>
Accept${' '}
<kbd data-slot="kbd" data-icon="inline-end" class=${cn(kbdClass(), 'translate-x-0.5')}><span aria-hidden="true">⏎</span><span class="sr-only">Enter</span></kbd>
</button>
`;
}
View Code
Tooltip
You can put a key inside <ui-tooltip-content> to display a tooltip with a keyboard key.
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import { buttonGroupClass } from '#components/ui/button-group.ts';
import { kbdClass, kbdGroupClass } from '#components/ui/kbd.ts';
// Each button sits inside its <ui-tooltip>, so the group's direct-child
// selectors land on the tooltip hosts; the buttons square their own joined
// corners instead.
export default function KbdTooltip() {
return html`
<div class="flex flex-wrap gap-4">
<div role="group" data-slot="button-group" data-orientation="horizontal" class=${buttonGroupClass()}>
<ui-tooltip>
<ui-tooltip-trigger>
<button type="button" data-slot="button" data-variant="outline" data-size="default" class=${cn(buttonClass({ variant: 'outline' }), 'rounded-e-none')}>Save</button>
</ui-tooltip-trigger>
<ui-tooltip-content>
Save Changes <kbd data-slot="kbd" class=${kbdClass()}>S</kbd>
</ui-tooltip-content>
</ui-tooltip>
<ui-tooltip>
<ui-tooltip-trigger>
<button type="button" data-slot="button" data-variant="outline" data-size="default" class=${cn(buttonClass({ variant: 'outline' }), 'rounded-s-none border-s-0')}>Print</button>
</ui-tooltip-trigger>
<ui-tooltip-content>
Print Document${' '}
<kbd data-slot="kbd-group" role="img" aria-label="Control plus P" class=${kbdGroupClass()}>
<kbd data-slot="kbd" class=${kbdClass()}>Ctrl</kbd>
<kbd data-slot="kbd" class=${kbdClass()}>P</kbd>
</kbd>
</ui-tooltip-content>
</ui-tooltip>
</div>
</div>
`;
}
View Code
Input Group
You can put a key inside an input group addon to display a keyboard key inside an input group.
import { html } from '@webjsdev/core';
import {
inputGroupClass, inputGroupAddonClass, inputGroupInputClass,
} from '#components/ui/input-group.ts';
import { kbdClass } from '#components/ui/kbd.ts';
import { SearchIcon } from '#lib/ui/lucide.ts';
export default function KbdInputGroup() {
return html`
<div class="flex w-full max-w-xs flex-col gap-6">
<div data-slot="input-group" role="group" class=${inputGroupClass()}>
<input data-slot="input-group-control" id="kbd-input-group" placeholder="Search..." aria-label="Search" class=${inputGroupInputClass()}>
<label data-slot="input-group-addon" data-align="inline-start" for="kbd-input-group" class=${inputGroupAddonClass()}>
${SearchIcon()}
</label>
<label data-slot="input-group-addon" data-align="inline-end" for="kbd-input-group" class=${inputGroupAddonClass({ align: 'inline-end' })}>
<kbd data-slot="kbd" class=${kbdClass()}><span aria-hidden="true">⌘</span><span class="sr-only">Command</span></kbd>
<kbd data-slot="kbd" class=${kbdClass()}>K</kbd>
</label>
</div>
</div>
`;
}
View Code
RTL
To enable RTL support, see the RTL configuration guide.
import { html } from '@webjsdev/core';
import { kbdClass, kbdGroupClass } from '#components/ui/kbd.ts';
const translations = {
en: { dir: 'ltr' },
ar: { dir: 'rtl' },
he: { dir: 'rtl' },
};
export default function KbdRtl() {
const lang = 'ar';
const { dir } = translations[lang];
return html`
<div class="flex flex-col items-center gap-4" dir=${dir} lang=${lang}>
<kbd data-slot="kbd-group" role="img" aria-label="Command Shift Option Control" class=${kbdGroupClass()}>
<kbd data-slot="kbd" class=${kbdClass()}>⌘</kbd>
<kbd data-slot="kbd" class=${kbdClass()}>⇧</kbd>
<kbd data-slot="kbd" class=${kbdClass()}>⌥</kbd>
<kbd data-slot="kbd" class=${kbdClass()}>⌃</kbd>
</kbd>
<kbd data-slot="kbd-group" role="img" aria-label="Control plus B" class=${kbdGroupClass()}>
<kbd data-slot="kbd" class=${kbdClass()}>Ctrl</kbd>
<span>+</span>
<kbd data-slot="kbd" class=${kbdClass()}>B</kbd>
</kbd>
</div>
`;
}
View Code
API Reference
kbdClass
Use kbdClass() on a native <kbd> element to display a keyboard key. It takes no options; merge your own classes with cn().
A key shown only as a symbol needs a spoken name. Do not put aria-label on the <kbd>, which browsers ignore there. Hide the glyph with aria-hidden="true" and add the spoken form in an sr-only sibling.
<kbd data-slot="kbd" class=${kbdClass()}>Ctrl</kbd>
<kbd data-slot="kbd" class=${kbdClass()}>
<span aria-hidden="true">⌘</span><span class="sr-only">Command</span>
</kbd>
kbdGroupClass
Use kbdGroupClass() to group keys together. To name a chord, give the group role="img" and an aria-label for the whole chord, so it is announced once as one thing.
<kbd data-slot="kbd-group" role="img" aria-label="Control plus B" class=${kbdGroupClass()}>
<kbd data-slot="kbd" class=${kbdClass()}>Ctrl</kbd>
<kbd data-slot="kbd" class=${kbdClass()}>B</kbd>
</kbd>