# Keyboard

> Keycap chip for rendering keyboard shortcuts in copy. Stack with a plain `+` between caps for chords.

Source: https://ngwr.dev/reference/components/keyboard  
Kind: Display

## Installation

```angular-ts
import { WrKbd } from 'ngwr/keyboard';

@Component({ imports: [WrKbd] })
export class MyComponent {}
```

## Basic

```angular-html
<wr-kbd>⌘</wr-kbd> + <wr-kbd>K</wr-kbd>
```

## Sizes

```angular-html
<wr-kbd size="sm">Esc</wr-kbd>
<wr-kbd size="md">Enter</wr-kbd>
<wr-kbd size="lg">⌫</wr-kbd>
```

## Full keyboard

Every cap rendered in a 60% ANSI-ish layout so glyphs, widths, and proportions can be eyeballed at once.

```angular-html
<!-- arrange caps in a grid via flex / grid -->
<wr-kbd>Esc</wr-kbd>
<wr-kbd>1</wr-kbd> <wr-kbd>2</wr-kbd> …
<wr-kbd>⌃</wr-kbd> <wr-kbd>⌥</wr-kbd> <wr-kbd>⌘</wr-kbd> <wr-kbd>Space</wr-kbd>
```

## Inside prose

Caps sit inline in running text. Their size is fixed per `size` rather than inherited, so match it to the surrounding variant — `md` reads level with body copy, `sm` with `small`. The glyphs render from `--wr-font-family-base`, not the mono stack, because `⌘` `⇧` `⌥` `⌃` are missing from many monospace fonts and would fall back to tofu.

```angular-html
<!-- wrTypography is a separate entry point: import { WrTypography } from
     'ngwr/typography'. An unknown attribute on a native <p> is not a template
     error, so without it the prose simply keeps the page's own styling. -->
<p wrTypography>
  Press <wr-kbd>⌘</wr-kbd> + <wr-kbd>P</wr-kbd> to open the command palette.
</p>
```

## API

| Name | Description | Type | Default |
| --- | --- | --- | --- |
| `size` | Visual size variant. | `'sm' \| 'md' \| 'lg'` | `'md'` |
| `CSS — --wr-kbd-bg` | Cap background. | `color` | `var(--wr-color-white)` |
| `CSS — --wr-kbd-border / --wr-kbd-border-bottom` | Side border / chunkier bottom border (the depth illusion). | `color` | `— dark @ 18% / 32%` |
| `CSS — --wr-kbd-color` | Glyph color. | `color` | `var(--wr-color-dark)` |
| `CSS — --wr-kbd-radius` | Corner radius. | `length` | `4px` |
| `CSS — --wr-kbd-shadow` | Drop shadow under the cap. | `shadow` | `0 1px 0 rgba(dark, 0.12)` |

## CSS variables

Custom properties `ngwr/keyboard` publishes. Each default below is declared on the component's own selector, so a `:root` override is shadowed by it — set them on that selector, on a wrapper you scope yourself, or inline on the element. Unlike the BEM class names, these are the supported way to restyle the component.

| Variable | Default | Declared on |
| --- | --- | --- |
| `--wr-kbd-bg` | `var(--wr-color-surface)` | `.wr-kbd` |
| `--wr-kbd-border` | `rgba(var(--wr-color-on-surface-rgb), 0.18)` | `.wr-kbd` |
| `--wr-kbd-border-bottom` | `rgba(var(--wr-color-on-surface-rgb), 0.32)` | `.wr-kbd` |
| `--wr-kbd-color` | `var(--wr-color-on-surface)` | `.wr-kbd` |
| `--wr-kbd-depth` | `1px` | `.wr-kbd` +1 variant override |
| `--wr-kbd-radius` | `var(--wr-control-radius-md)` | `.wr-kbd` +2 variant overrides |
| `--wr-kbd-shadow` | `0 var(--wr-kbd-depth) 0 rgba(var(--wr-color-backdrop-rgb), 0.25)` | `.wr-kbd` |

## See also

- [Keyboard](https://ngwr.dev/guides/keyboard) — How chords, keycaps and key primitives fit together in one task.
- [WrHotkey](https://ngwr.dev/reference/services/hotkey) — Bind the chord this keycap advertises.