> For the complete documentation index, see [llms.txt](https://docs.monarchlinux.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.monarchlinux.com/basics/niri.md).

# Niri

Understand Monarch's Niri desktop model and keep custom configuration upgrade-safe.

Niri is Monarch's Wayland compositor. It places windows in a scrollable strip of columns instead of a traditional overlapping desktop.

## Work with windows

| Action                               | Shortcut                         |
| ------------------------------------ | -------------------------------- |
| Focus a column or window             | **SUPER + Arrow keys**           |
| Move a column or window              | **SUPER + SHIFT + Arrow keys**   |
| Resize the focused column            | **SUPER + CTRL + - / =**         |
| Resize the focused window vertically | **SUPER + CTRL + SHIFT + - / =** |
| Toggle floating mode                 | **SUPER + SHIFT + Space**        |
| Toggle fullscreen                    | **SUPER + F**                    |
| Toggle full-width column             | **SUPER + SHIFT + F**            |
| Cycle preset column widths           | **SUPER + R**                    |
| Toggle tabbed columns                | **SUPER + ALT + Enter**          |
| Show all workspaces                  | **SUPER + Tab**                  |

See [Keybindings](/basics/keybindings.md) for the complete Monarch shortcut reference. Press **SUPER + K** to see the current bindings directly on your system.

## Customize Niri safely

Monarch assembles Niri's configuration from packaged defaults and user overrides:

| Path                             | Owner                                         |
| -------------------------------- | --------------------------------------------- |
| `~/.config/niri/config.kdl`      | Generated and maintained by Monarch           |
| `~/.config/niri/user.kdl`        | Your overrides                                |
| `~/.config/niri/workspaces.conf` | Your persistent workspace names               |
| `~/.config/niri/runtime.kdl`     | Generated live settings such as display scale |

{% hint style="warning" %}
Do not edit `config.kdl`, `runtime.kdl`, or files under `/usr/share/monarch/default/niri/`. They can be regenerated by Monarch.
{% endhint %}

Open **Monarch Menu → Settings → Config → Niri** to edit `user.kdl`. Monarch loads this file last, so an overridden setting or shortcut wins over the default while unrelated defaults keep receiving updates.

After a manual edit, rebuild, validate, and reload the complete configuration:

```bash
monarch refresh niri
```

You can also validate it without reloading:

```bash
niri validate -c ~/.config/niri/config.kdl
```

## Rename workspaces

Edit `~/.config/niri/workspaces.conf`. Each non-comment line defines one persistent workspace, in order from **SUPER + 1** through **SUPER + 0**. Then run:

```bash
monarch refresh niri
```

The generated workspace names are shared by Niri's bindings and the Noctalia bar, so they stay in sync.

## Recover the managed configuration

If the generated entry point is damaged, run `monarch refresh niri`. Monarch backs up a changed `config.kdl`, rebuilds it, validates the assembled configuration, and reloads a running Niri session. Your `user.kdl` remains separate; if validation still fails, correct the override reported by Niri.