Modus/docs/configuration.md

Configuration Guide

Modus is configured via TOML files in the config/ directory, plus a graphical Settings window.

File Overview

File	Purpose	Reload
config.toml	Main settings (features, widgets, paths)	Restart
mods.toml	Custom panel buttons (menus, shell commands)	Instant
dock.toml	Pinned dock apps	Restart

Settings Window

Press Super + I to open the Settings window. It provides a GUI for most config.toml options organized into tabs:

• General: Debug mode, weather location, keyboard layouts, night light, switcher preview
• Dock: Enable/disable, auto-hide, icon size, special workspace apps
• Panel: All panel widgets (global menu, systray, control center, etc.), wallpapers directory
• Notifications: Timeout, ignored apps, limited history apps

Changes save to config.toml immediately. Some settings require a restart.

You can also toggle settings from the terminal:

fabric-cli exec modus "settings.toggle()"

---

config.toml (Main Settings)

Auto-generated on first run with sensible defaults. Most changes require restarting Modus (uv run start).

General

Key	Type	Default	Description
debug	bool	false	Enable verbose logging
weather_location	string	""	City for weather widget (e.g., "London, UK")
keyboard_layouts	array	["us"]	Active keyboard layouts
night_light_temperature	int	4500	Night light color temp in Kelvin
wallpapers_dir	string	"src/assets/wallpaper_example/"	Path to wallpapers folder
switcher_live_preview	bool	true	Live window previews in switcher
switcher_live_preview_delay_ms	int	200	Preview framerate delay (lower = smoother)

Dock

Key	Type	Default	Description
dock_enabled	bool	true	Show the dock
dock_auto_hide	bool	true	Hide when windows overlap
dock_always_occluded	bool	false	Keep dock behind windows
dock_icon_size	int	52	Icon size in pixels
dock_hide_special_workspace_apps	bool	true	Hide special workspace apps

Panel Widgets

Key	Type	Default	Description
imac_button	bool	true	Apple logo button
systray	bool	true	System tray
control_center	bool	true	Control center widget
search	bool	true	Search/spotlight button
global_menu	bool	true	App menus in panel
network	bool	true	Network indicator
battery	bool	true	Battery indicator
bluetooth	bool	true	Bluetooth indicator
date_time	bool	true	Date/time indicator
workspace_indicator	bool	true	Workspace indicator
notification_center	bool	true	Notification center
custom_mods	bool	true	Custom panel buttons from mods.toml
window_switcher	bool	true	Alt-Tab window switcher
osd	bool	true	Volume/brightness on-screen display
hide_special_workspace	bool	true	Hide special workspace from indicators

Notifications

Key	Type	Default	Description
notification_timeout	string	"5s"	Auto-dismiss duration
notification_ignored_apps	array	["Hyprshot"]	Apps with suppressed notifications
notification_limited_apps_history	array	["Spotify"]	Apps with limited history
systray_ignore	array	["blueman", "network"]	Icons hidden from system tray

---

Keybinds

Defined in config/hypr/modus.lua:

Key	Action
Super + D	Spotlight search
Super + E	Emoji picker
Super + V	Clipboard history
Super + W	Wallpaper browser
Super + I	Settings window
Super + L	Lock screen
Super + Z	Screencapture toggle
Super + S	Screenshot region
Alt + Tab	Window switcher
Alt + Space	Keyboard layout switch
Super + Shift + R	Reload Modus
Super + Shift + Y	Reload CSS
Alt + Shift + W	Random wallpaper

---

mods.toml (Custom Panel Buttons)

Define custom buttons for the top panel. Changes reload instantly!

[Mods.terminal]
icon = "terminal.svg"
icon-size = 16
order = 1
on-clicked = "kitty"

[Mods.color-picker]
icon = "misc/color-picker.svg"
icon-size = 22
order = 0
on-left = "hyprpicker -a -n -f hex | wl-copy"
on-right = "hyprpicker -n -f hsv | wl-copy"

[Mods.power-menu]
icon = "power.svg"
icon-size = 18
order = 2
on-left = "wlogout"

Properties:

• icon — SVG filename in src/assets/icons/
• icon-size — defaults to 16
• order — left-to-right position (lower = first)
• on-clicked, on-left, on-right, on-middle — shell commands via sh -c
• on-scroll-up, on-scroll-down — scroll event commands
• options — dropdown menu entries (each with label + on-clicked)
• Full shell syntax (&&, |) supported

---

dock.toml (Pinned Apps)

pinned = [
    "firefox",
    "kitty",
    "org.gnome.Nautilus"
]

Use the exact .desktop file name or application ID.