# Kbd

Used to display textual user input from keyboard.

Source: https://webjs.dev/ui/docs/components/kbd

```ts
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>
  `;
}
```

## Installation

```bash
npx @webjsdev/ui add kbd
```

### Copy and paste the following code into your project.

````ts title="components/ui/kbd.ts"
/**
 * 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

```ts
import { kbdClass, kbdGroupClass } from '#components/ui/kbd.ts';
```

```ts
<kbd data-slot="kbd" class=${kbdClass()}>Ctrl</kbd>
```

## Composition

Use the following composition to build `kbdClass` and `kbdGroupClass`:

```text
kbdClass
kbdGroupClass
├── kbdClass
└── kbdClass
```

## Group

Use `kbdGroupClass()` to group keyboard keys together.

```ts
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>
  `;
}
```

## Button

Put a `kbdClass()` key inside a button to display a keyboard key inside the button.

```ts
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>
  `;
}
```

## Tooltip

You can put a key inside `<ui-tooltip-content>` to display a tooltip with a keyboard key.

```ts
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>
  `;
}
```

## Input Group

You can put a key inside an input group addon to display a keyboard key inside an input group.

```ts
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>
  `;
}
```

## RTL

To enable RTL support, see the [RTL configuration guide](https://webjs.dev/ui/docs/rtl).

```ts
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>
  `;
}
```

## 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.

```ts
<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.

```ts
<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>
```
