# Kbd

> Keyboard shortcuts drawn as keys, with symbols on macOS. A native Pyzed component for Python desktop GUIs, with a live preview, code examples and its API.

Source: https://albakore.github.io/pyzed/library/kbd/

:::tip[In plain words]
Draws keyboard keys, so people learn the shortcut: Ctrl + S.
:::

Draws a shortcut written as a string (`"ctrl-shift-p"`, chords like `"cmd-k cmd-s"`) as key caps. On macOS it uses symbols (⌘⇧P) and words elsewhere; `pyzed.ui.base.KEY_STYLE` forces `"symbols"` or `"words"`. `ui.format_keys` returns the labels if you draw them yourself.

`ui.kbd` · Category: [Display](https://albakore.github.io/pyzed/library/#display) · [Full reference →](https://albakore.github.io/pyzed/reference/ui/#kbd)

**Code:**

```python
pz.column([
    ui.kbd("ctrl-shift-p"),
    ui.kbd("ctrl-k ctrl-s"),
    pz.row([ui.kbd("escape", size="xs"), ui.kbd("enter", size="xs"), ui.kbd("tab", size="xs")], spacing=8),
], spacing=12, align="center")
```

## When to use

- In menus, tooltips, palettes and help screens, to teach shortcuts.
- Most components already accept `keys=` and draw it for you (button, menu item, tooltip).

## Usage

```python
import pyzed as pz
from pyzed import ui

pz.column([
    ui.kbd("ctrl-shift-p"),
    ui.kbd("ctrl-k ctrl-s"),
    pz.row([ui.kbd("escape", size="xs"), ui.kbd("enter", size="xs"), ui.kbd("tab", size="xs")], spacing=8),
], spacing=12, align="center")
```

## Variants

:::note[About these captures]
Each capture is recorded by pyzed itself, off-screen at 2x, in One Dark or One Light to match this site's theme, and cropped to the component so it shows at its real size. The pointer hovers, presses or types into it; a component that does not react to the pointer cycles through a few themes. With reduced motion you see the first frame. Open **Code** under a capture to see the snippet that draws it; free names such as `on_save` stand for your own callbacks.
:::

### Keys

Write shortcuts as `"ctrl-s"`; on macOS `ctrl` becomes ⌃ and `cmd` ⌘ automatically.

```python
ui.kbd("enter")
```

```python
ui.kbd("ctrl-shift-p")
```

```python
ui.kbd("ctrl-k ctrl-s")
```

```python
pz.row([ui.kbd("escape"), ui.kbd("tab"), ui.kbd("backspace"), ui.kbd("up")], spacing=6)
```

### Size

```python
ui.kbd("ctrl-p", size="xs")
```

```python
ui.kbd("ctrl-p", size="sm")
```

## Events

Kbd has no events of its own: it shows what you give it. Like every widget it also has the **18 common events** (`click`, `double_click`, `right_click`, `mouse_enter`, `drag`, `key_down`, `resize`…), attached with `.on(...)`: see [Events](https://albakore.github.io/pyzed/guides/events/) and [Events of every component](https://albakore.github.io/pyzed/library/events/).

## Properties and API

### `ui.kbd`

```python
kbd(keys, *, size='sm', theme=None)
```

Draws a shortcut as keys: `"ctrl-shift-p"`, `"cmd-k cmd-s"`. Uses symbols on macOS (⌘⇧P) and words elsewhere.

| Property | Default | Description |
| --- | --- | --- |
| `keys` | *required* | The shortcut. |
| `size` | `"sm"` | `"xs"` or `"sm"`. |
| `theme` | `None` | Theme to use instead of the current one (`pyzed.theme.current()`). |

[Full reference →](https://albakore.github.io/pyzed/reference/ui/#kbd)

### `ui.format_keys`

```python
format_keys(keys)
```

Splits a shortcut into labels per chord: `format_keys("ctrl-shift-p") == [["Ctrl", "Shift", "P"]]`. The style is controlled by `pyzed.ui.base.KEY_STYLE` (`"auto"`, `"symbols"` or `"words"`).

| Property | Default | Description |
| --- | --- | --- |
| `keys` | *required* | The shortcut. |

[Full reference →](https://albakore.github.io/pyzed/reference/ui/#format_keys)

### `ui.keys_text`

```python
keys_text(keys)
```

A shortcut as plain text for a label or a status line: `keys_text("ctrl-shift-p") == "Ctrl+Shift+P"` (`"⌃⇧P"` with macOS symbols), chords separated by a space. Tooltips, buttons and menus take `keys=` instead and draw key caps, so never write the keys into their text.

| Property | Default | Description |
| --- | --- | --- |
| `keys` | *required* | The shortcut. |

[Full reference →](https://albakore.github.io/pyzed/reference/ui/#keys_text)

## Related

- [Keybinding hint](https://albakore.github.io/pyzed/library/keybinding-hint/): A muted “Open file Ctrl P” hint.
- [Shortcuts](https://albakore.github.io/pyzed/library/shortcuts/): A searchable list of key bindings, grouped.
- [Tooltip](https://albakore.github.io/pyzed/library/tooltip/): A hint shown on hover, optionally with its shortcut.