Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/zirconium-dev/zirconium/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Niri is a scrollable-tiling Wayland compositor that serves as the window manager in Zirconium. It provides a unique tiling experience where workspaces are organized horizontally and windows can be arranged in a scrollable layout.
Niri is installed from the yalter/niri-git COPR repository and runs as the default session manager launched by dms-greeter.

​
Configuration files

Niri configuration is managed through several locations:

​
User configuration

  • Main config: ~/.config/niri/config.kdl
  • Managed by: chezmoi (from zdots)
  • Source: /usr/share/zirconium/zdots/

​
System configuration

  • Greeter config: /etc/greetd/config.toml
  • Session command: dms-greeter --command niri
Your Niri configuration is automatically managed by chezmoi and synchronized with the system zdots. Any manual changes will be overwritten during OS updates unless you disable automatic dotfile updates.

​
Key configuration options

​
Environment variables

Zirconium sets up the following environment variables for optimal Niri experience: 
# /etc/profile.d/zirconium-font-settings.sh
export FREETYPE_PROPERTIES="cff:no-stem-darkening=0 autofitter:no-stem-darkening=0"

​
Window manager features

Niri in Zirconium includes:
  • Scrollable tiling: Horizontal workspace navigation with infinite scrolling
  • Wayland-native: Full Wayland support with XWayland fallback via xwayland-satellite
  • Dynamic layouts: Automatic window arrangement and resizing
  • Multi-monitor support: Native support for multiple displays

​
Keybindings and customization

Niri keybindings are defined in ~/.config/niri/config.kdl. The default configuration is managed through zdots.

​
Common operations

While specific keybindings are defined in your zdots configuration, Niri typically supports:
  • Window navigation and movement
  • Workspace switching
  • Layout adjustments
  • Application launching via DankMaterialShell
If you need to reset your Niri configuration to defaults:
zjust reset-niri
This command will:
  1. Prompt for confirmation (requires gum)
  2. Reset ~/.config/niri to the zdots defaults
  3. Preserve your other configurations

​
Auto-rotation support

Zirconium includes automatic screen rotation support for convertible devices through the iio-niri service.

​
Managing auto-rotation

systemctl status --user iio-niri.service
The service configuration is located at /usr/lib/systemd/user/iio-niri.service: 
[Unit]
Description=Autorotation service
PartOf=graphical-session.target
After=graphical-session.target

[Service]
ExecStart=iio-niri
Restart=on-failure
RestartSec=1

[Install]
WantedBy=graphical-session.target

​
Customizing Niri

​
Direct configuration editing

You can edit Niri configuration directly, but be aware that changes may be overwritten: 
# Edit your Niri config
$EDITOR ~/.config/niri/config.kdl

# Reload Niri to apply changes
niri msg action reload-config
Manual changes to ~/.config/niri/config.kdl will be overwritten when chezmoi updates run (typically on OS updates or when running zjust zdots-update).

​
Persistent customization

For persistent Niri customization:
  1. Disable automatic dotfile updates if you want full control: 
    zjust toggle-automatic-dotfiles
  2. Fork zdots and customize the Niri configuration there
  3. Use chezmoi templates to conditionally apply your customizations
See the customization guide for more details on managing dotfiles.

​
Additional tools

Niri integrates with several Zirconium components:
  • DankMaterialShell: Provides the UI shell, launcher, and panels
  • udiskie: Automatic USB device mounting (systemd user service)
  • fcitx5: Input method framework for multilingual input
  • xdg-desktop-portal-gnome: Desktop integration for file pickers and screenshots

​
Troubleshooting

​
Niri won’t start

Check the greetd logs: 
journalctl -u greetd.service -b

​
Configuration errors

Validate your Niri configuration: 
niri validate ~/.config/niri/config.kdl

​
Reset to defaults

Use the built-in reset command: 
zjust reset-niri

​
Next steps

DankMaterialShell

Configure the UI shell and launcher

Customization

Learn about dotfiles and theming

Build docs developers (and LLMs) love

Get started for freeTalk to us