---
title: "WezTerm Keyboard Concepts"
aliases: [wezterm-keyboard, wezterm-input, wezterm-keys-concepts]
tags: [wezterm, keyboard, terminal, dotfiles, input]
sources: [raw/Keyboard Concepts - Wez's Terminal Emulator.md]
created: 2026-04-17
updated: 2026-04-17
---

## Overview

WezTerm's keyboard system sits between OS-level input mechanisms (IME, keyboard layouts, dead keys) and terminal key assignments. Understanding the distinction between *physical* vs *mapped* keys, and how modifiers interact with composed characters, is essential for writing correct key bindings.

## OS-Level Input Concepts

| Concept | What it is |
|---------|------------|
| **IME** (Input Method Editor) | OS service for rich text composition (Asian scripts, emoji, dead keys). WezTerm can delegate to it via `use_ime = true` |
| **Keyboard Layout** | OS mapping from physical key → locale-appropriate character. Opaque to apps, changeable at runtime |
| **Dead Key** | Modal key that produces no immediate output; composes with the next keypress (e.g. `^` + `e` → `ê`) |
| **Physical Key** | Key identified by hardware location — as if ANSI US layout were active, regardless of actual layout |
| **Mapped Key** | Key identity *after* the OS keyboard layout has been applied |
| **Modifier** | `SHIFT`, `CTRL`, `CMD`, `ALT` — held simultaneously; limited by hardware to these four |

## WezTerm-Level Concepts

- **Key Assignment** — an action bound to a specific key + modifier combo
- **Key Table** — a named group of key assignments; WezTerm maintains a *stack* of active tables per window, enabling modal input (see [[wiki/dotfiles/wezterm-key-tables|WezTerm Key Tables]])
- See [[wiki/dotfiles/wezterm-key-bindings|WezTerm Key Bindings]] for how to write assignments with `phys:`, `mapped:`, `raw:` prefixes

## Alt / Option Key Behavior

### AltGr Layouts (European keyboards)
- WezTerm respects AltGr composition from the OS (e.g. German `AltGr <` → `|`)
- If physical keyboard doesn't match OS layout, right `Alt` is treated as `AltGr`
- Left `Alt` = plain modifier, no composition

### macOS Left vs Right Option
```lua
config.send_composed_key_when_left_alt_is_pressed = false  -- Left Opt = Alt modifier only
config.send_composed_key_when_right_alt_is_pressed = true   -- Right Opt = AltGr / composition
```
- Right Opt + `n` then `n` → `ñ`; Right Opt + `n` then `SPACE` → `~`

### Windows Ctrl-Alt ↔ AltGr
- Enable `treat_left_ctrlalt_as_altgr` when using VNC with dead-key layouts

## Dead Keys

Default behavior: dead key "holds" state until next keypress → combined diacritic character.

```lua
config.use_dead_keys = false  -- disable dead-key hold; emit immediately
```

- Disabling is useful for Vi users who want `^` as a single keypress
- On X11 with `use_ime = true`, the IME may handle dead keys independently — WezTerm cannot override it

## IME Support

- Enabled via `use_ime = true` — see upstream docs for per-OS support status
- When `use_ime = false`, WezTerm performs its own dead-key expansion

## Composed Keys in Assignments

- When a key combo produces a composed character, WezTerm checks **both** the composed and uncomposed versions against your key mappings
- First match wins and takes precedence over default terminal processing

## Key Takeaways

- **Physical vs Mapped**: use `phys:` prefix in bindings to target hardware location regardless of OS layout; use `mapped:` (default) to target the layout-translated key
- **Left Alt ≠ Right Alt on macOS**: left sends `Alt` modifier, right performs composition by default
- **Dead keys are on by default**: set `use_dead_keys = false` to get immediate `^` / `~` / etc. in Vi
- **IME and dead keys can conflict**: disabling IME (`use_ime = false`) gives WezTerm full control over dead-key handling
- **Key Tables enable modal input**: stack multiple tables for Vim-style modal keymaps (see [[wiki/dotfiles/wezterm-key-tables|Key Tables]])
- Composed-key assignments check both raw and composed forms — safe to bind `ALT+n` even when right-opt composes

## Sources

- [wezterm.org/config/keyboard-concepts.html](https://wezterm.org/config/keyboard-concepts.html)
