# Shortcut keys
> Keycaps drawn in dots with their key names set in type; they press down while the real keys are held and fire `trigger` when the combination is down.
- Element: `<hf-kbd>`
- React: `import { HfKbd } from "@/components/lumesec/hf-kbd"`
- Collection: Pixel HD (https://elements.lumesec.ai/components/pixel-hd)
- Registry item: https://elements.lumesec.ai/r/hf-kbd.json
- Page: https://elements.lumesec.ai/components/pixel-hd/kbd



Live preview: https://elements.lumesec.ai/view/hf-kbd

```html
<hf-kbd keys="Mod+K" label="Open command palette"></hf-kbd>
```

## Playground

Change a prop and the component updates. Props marked live animate to the new value; the others rebuild the element.

## Installation

```bash
npx shadcn@latest add @lumesec/hf-kbd
```

First time with the @lumesec registry? Register it once, or install by URL:

```bash
npx shadcn@latest registry add @lumesec=https://elements.lumesec.ai/r/{name}.json
npx shadcn@latest add https://elements.lumesec.ai/r/hf-kbd.json
```

## Usage

React:

```tsx
import { HfKbd } from "@/components/lumesec/hf-kbd";

export function Example() {
  return (
    <HfKbd keys="Mod+K" label="Open command palette" />
  );
}
```

HTML:

```html
<script type="module" src="https://elements.lumesec.ai/cdn/hf-kbd.js"></script>

<hf-kbd keys="Mod+K" label="Open command palette"></hf-kbd>
```

## Behaviour

Keycaps drawn in dots, with the key names set in type, that light up and press down when you hold the real keys, and fire a `trigger` event when the whole combination is down.

## API reference

### Attributes

| Attribute | React prop | Type     | Default | Description                                                                                                                                                                                                                                                                                                   |
| --------- | ---------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `keys`    | `keys`     | `string` | `Mod+K` | Key combination separated by `+`. `Mod` is ⌘ on Apple platforms and Ctrl elsewhere. Named keys: `Ctrl`, `Cmd` / `Meta`, `Shift`, `Alt` / `Option`, `Enter`, `Esc` / `Escape`, `Tab`, `Space`, `Up`, `Down`, `Left`, `Right`, `Backspace`; any other name is compared with `KeyboardEvent.key`, ignoring case. |
| `label`   | `label`    | `string` | —       | Text shown beside the keycaps.                                                                                                                                                                                                                                                                                |

### Events

Events bubble and cross the shadow boundary unless the description says otherwise.

| Event     | React prop  | Detail                     | Description                                                                                                                                                                                      |
| --------- | ----------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `trigger` | `onTrigger` | `{ keys: string \| null }` | Fires when a keydown of one of the keys leaves the whole combination held. Auto-repeat keydowns do not fire it again. `keys` is the raw attribute value, or `null` when the attribute is absent. |

### Properties

| Property           | Type       | Description             |
| ------------------ | ---------- | ----------------------- |
| `keys` (read-only) | `string[]` | The parsed combination. |

## Keyboard

| Keys                                           | Action                                                                                                                          |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Any key in `keys` (listened for on `document`) | Presses its keycap while held and releases it on keyup. When every key is down, fires `trigger`. Window blur releases all keys. |

## Accessibility

* The keys are text in a `<kbd>` with one nested `<kbd>` per key; the dot canvas behind them is `aria-hidden`. A symbol such as `⌘` or `⇧` is `aria-hidden` and followed by a visually hidden name (`Command`, `Shift`), so screen readers read the key names.
* The element is not focusable. It listens to `keydown` and `keyup` on `document` in the capture phase and does not call `preventDefault()`, so the browser and page still handle the keys.
* Reduced motion: the key text moves and changes colour without a transition; the release glow on the caps fades over about 0.4 s either way.

## Theming

The element reads your shadcn theme tokens through its shadow root, so light and dark follow your theme. The accent comes from `--lumesec`. See [Theming](/docs/theming).

This component reads `--foreground`, `--lumesec` and `--lumesec-shine`.

To restyle only LumeSec elements, set the matching `--ui-*` overrides: `--ui-accent`, `--ui-fg`, `--ui-mono` and `--ui-shine`.

## Notes

* The keycaps are laid out by their text, and the dots follow when the size changes; `keys` and `label` are read once on connect and are not observed.
* Matching uses `KeyboardEvent.key`, so combinations whose key value changes under a modifier (for example Option+letter on macOS) may not match.
* Every instance listens globally, so two elements with the same `keys` both fire.