# Niri Wayland Compositor

Niri is a scrollable-tiling Wayland compositor. Windows are arranged in columns that scroll horizontally. It uses KDL-format configuration with an include-based modular structure.

**Version:** 26.04 (8ed0da4)
**Config:** `~/.config/niri/config.kdl`

---

## Configuration Structure

```
~/.config/niri/
├── config.kdl          # Main entry, includes all modules
├── noctalia.kdl        # Generated by noctalia (theme colors)
└── cfg/
    ├── animation.kdl   # Spring and curve animations
    ├── autostart.kdl   # Startup applications (noctalia, handy --start-hidden)
    ├── display.kdl     # SYMLINK to the active desk-*.kdl profile (see displays)
    ├── desk-1-home.kdl      # Desk profile: home rig (EDID-keyed)
    ├── desk-2-portable.kdl  # Desk profile: portable monitor (skeleton)
    ├── input.kdl       # Keyboard, touchpad, mouse
    ├── keybinds.kdl    # All key bindings
    ├── layout.kdl      # Gaps, column widths, struts
    ├── rules.kdl       # Window and layer rules
    ├── switch-events.kdl # Lid-close -> noctalia lock-and-suspend (blankpad)
    └── misc.kdl        # Environment, cursor, blur
```

## Layout

Column-based scrollable tiling. Columns are cycled with Mod+Left/Right (or Mod+H/L). Windows within columns stack vertically.

| Setting | Value |
|---------|-------|
| **Gaps** | 16px |
| **Center focused column** | Never |
| **Background** | Transparent (for Noctalia wallpaper) |
| **Column presets** | 12.5%, 25%, 33%, 50%, 67%, 75%, 87.5% (Mod+R / Mod+Shift+R) |

## Input

| Setting | Value |
|---------|-------|
| **Focus follows mouse** | Enabled |
| **Workspace back-and-forth** | Enabled |
| **Numlock** | Enabled on startup |
| **Touchpad tap** | Enabled |

## Window Rules

| Rule | Match | Effect |
|------|-------|--------|
| All windows | — | 20px corner radius, clipped |
| Steam (non-window) | `app-id="steam"`, exclude title `Steam` | Open floating |
| Steam notifications | `app-id="steam"`, title `notificationtoasts_*` | Floating, bottom-right |
| Noctalia wallpaper | namespace `noctalia-wallpaper*` | Place in backdrop |
| Noctalia settings | `app-id="dev.noctalia.Noctalia"` | Floating 1080x920 |
| Noctalia layers | namespace `^noctalia-(bar|notification|dock|panel|attached-panel|osd)` | blur xray=false |

## Environment Variables

| Variable | Value | Purpose |
|----------|-------|---------|
| `ELECTRON_OZONE_PLATFORM_HINT` | `auto` | Electron Wayland support |
| `QT_QPA_PLATFORM` | `wayland` | Qt Wayland |
| `QT_QPA_PLATFORMTHEME` | `gtk3` | Qt GTK theme |
| `QT_WAYLAND_DISABLE_WINDOWDECORATION` | `1` | Remove Qt CSD |
| `XDG_CURRENT_DESKTOP` | `niri` | Desktop identification |
| `XDG_SESSION_TYPE` | `wayland` | Session type |

## Animations

| Animation | Type | Parameters |
|-----------|------|------------|
| Workspace switch | Spring | damping-ratio=1.0 stiffness=1000 |
| Window open | Duration | 200ms, ease-out-quad |
| Window close | Duration | 200ms, ease-out-cubic |
| Window movement | Spring | damping-ratio=1.0 stiffness=800 |
| Window resize | Spring | damping-ratio=1.0 stiffness=1000 |

---

## Concept Files

| File | Type | Description |
|------|------|-------------|
| [[action-reference|action-reference.md]] | reference | Curated reference of niri actions |
| [[default-bindings|default-bindings.md]] | reference | Default key bindings organized by category |
| [[key-bindings-syntax|key-bindings-syntax.md]] | reference | KDL configuration syntax for key bindings |
| [[tips|tips.md]] | howto | Practical tips for working with niri |
| [[displays|displays.md]] | reference | Desk-profile system: EDID-keyed outputs, hotplug auto-switch, portrait transforms, GPU notes |
| [[keybindings|keybindings.md]] | reference | GENERATED keybinding cheat sheet (scripts/gen-keybinds.sh) |
| [[screenshots|screenshots.md]] | reference | Screenshot bind matrix: flameshot vs niri-native, 2+ output limits, all-monitor capture |

---

## See Also

- [[noctalia-shell|noctalia-shell]] — Desktop shell integration
- [[displays|displays]] — Multi-monitor desk rig configuration
- [[cachyos|cachyos]] — Operating system