---
type: reference
title: Niri Key Bindings Syntax
description: Configuration syntax for niri key bindings — KDL format, modifiers, bind options, and finding key names with wev.
tags:
  - niri
  - keybindings
  - kdl
  - configuration
verified: 2026-08-28
---

# Key Bindings Syntax

Key bindings go in the `binds {}` section of the config file (`~/.config/niri/config.kdl`):

```kdl
binds {
    Mod+T { spawn "alacritty"; }
    Mod+Left { focus-column-left; }
}
```

## Modifiers

- `Ctrl` or `Control`
- `Shift`
- `Alt`
- `Super` or `Win`
- `ISO_Level3_Shift` or `Mod5` (AltGr)
- `ISO_Level5_Shift` (for lv5 options like `lv5:caps_switch`)
- `Mod` — Special: equals `Super` on TTY, equals `Alt` in nested window

## Bind Options

```kdl
binds {
    Mod+T repeat=false { spawn "alacritty"; }     // Do not repeat on hold
    Mod+T cooldown-ms=500 { spawn "alacritty"; }  // Rate-limit
    Super+Alt+L allow-when-locked=true { spawn "swaylock"; }  // Works when locked
    Mod+Q hotkey-overlay-title="Close Window" { close-window; }  // Custom title in overlay
    Mod+Escape allow-inhibiting=false { ... }     // Always works (even with inhibitors)
}
```

## Finding Key Names

Use [`wev`](https://git.sr.ht/~sircmpwn/wev) to find XKB key names:

```bash
wev
# Then press the key you want to bind — look at `sym: XXXX` in output
```

Shifted keys require Shift + the unshifted key (for example, `Mod+Shift+Comma` for `<` on US QWERTY).

## Constraints

- One action per keybind. Each `{ ... }` block holds exactly one action; multiple actions like `{ move-window-up; consume-or-expel-window-up; }` are rejected at parse time.
- No duplicate keys. The same key combo (e.g. `Mod+CTRL+Left`) can only appear once in `binds {}`. Adding a new binding for an existing key causes a parse error.
- Valid consume/expel actions: `consume-or-expel-window-left`, `consume-or-expel-window-right`, and `expel-window-from-column`. The `consume-or-expel-window-up`/`-down` variants do NOT exist.

## Related

* [Default Key Bindings](/tools/niri/default-bindings.md) — What niri ships with out of the box
* [Action Reference](/tools/niri/action-reference.md) — All available actions