Configuration

Configuration

~/.config/synui/synuirc is the compositor's config file. One key = value per line, # for a comment. It is read at startup and on Super+Shift+R.

Most of these have a panel, and the panel is usually the better door — Control panel (Super+C) writes settings.state, which is read after synuirc and therefore wins. This page is the complete list of what the parser accepts, for the things no panel reaches and for anyone configuring a machine from a file.

The authoritative copy is the header comment at the top of synui/src/config.c. If this page and that file disagree, the file is right.

Where a setting can come from

Later sources win:

compiled defaults	config_set_defaults()
/etc/synui/synuirc	system-wide — what the live ISO ships
~/.config/synui/synuirc	yours
the .state files	written by the panels — settings.state, dock.state, binds.state, power.state, …

That ordering is why a panel beats a config line: a .state file is a thing you did, and a synuirc line is a thing you set up.

---

Keyboard

Key	Values
xkb_layout	us	The layout synui uses
xkb_variant	colemak
xkb_model	pc105
xkb_options	ctrl:nocaps	Comma-separated
xkb_rules	evdev
repeat_delay	600	ms held before a key repeats
repeat_rate	25	repeats per second once it does
numlock	on off	at login

⚠ The console keymap does not reach Wayland. vconsole.conf is a separate answer — which is why the installer asks once and writes both.

Pointer

Key	Values
accel_speed	-1.0–1.0	0 is the driver's own
natural_scroll	on off	unset follows the device default
left_handed	on off	swaps the buttons
tap	on off	tap-to-click
focus_mode	click sloppy strict
focus_delay_ms	0–3000	how long the pointer rests before focus follows
cursor_theme	Adwaita
cursor_size	8–256
snap_zone	2–200 px	how close to an edge a drag arms the snap
panel_follow_pointer	on off	does a panel open on the pointer's monitor

focus_mode: Click — only a click focuses. Sloppy and Strict both follow the pointer; over the desktop, Strict drops focus and Sloppy keeps the last window.

Windows

Key	Values
border_width	0–32
border_color_norm	#RRGGBB	unfocused frame
border_color_focus	#RRGGBB	focused
border_color_ai	#RRGGBB	a window the AI is holding context for
border_color_warn	#RRGGBB	one synguard has flagged
titlebar_height	0, or 14–64	0 removes it; below 14 there is no room for a button
titlebar_color / titlebar_color_focus	#RRGGBB	caption, unfocused / focused
titlebar_text / titlebar_text_focus	#RRGGBB	caption text
corner_radius	0–48	forced square while maximized
shadow	on off
shadow_color _opacity _blur_sigma _spread _offset_x _offset_y		spread is solid shadow before the falloff — what gives it weight
remember_geometry	on off	reopen each app where and how big it was

⚠ The four border colours are overridden by the theme. Every preset carries its own, so a line here only shows on a desktop whose theme has not spoken — which is none of the fifteen. They are the pre-theme mechanism, kept because a pushed custom palette still uses them.

Blur

blur = on|off, then blur_radius (1–20), blur_passes (1–5), blur_noise, blur_brightness, blur_contrast, blur_saturation, and glass_halo (0–64 — how far the blur reaches past the window).

Blur frosts what is behind a translucent window. An opaque one costs nothing: there is nothing to see through.

Animation

Key	Values
anim_window	fade rise scale none
anim_window_ms	0 jumps straight to the end state
anim_rise_px	0–200 — Rise only
anim_workspace	fade slide none
anim_workspace_ms	a slide wants longer than a fade
anim_curve	linear ease-in ease-out ease-in-out

Closing is not animated, and cannot be: the client's buffer is gone the moment it unmaps, so there is nothing left to animate.

Layout

gap (0–128), master_factor (share the master window takes), float_inset (0–40 % kept clear at each edge by the floating grid), float_gap (0–256 px between those tiles), cascade_stack_max (windows per pile).

Transparency

transparency = on|off is the master switch for see-through windows — off, the rest do nothing. Then active_opacity, inactive_opacity, and foot_alpha for the terminal, which needs its own number because foot and syntty draw their own background with the glyphs left opaque.

The desktop-wide glass slider and its switches are on The Desktop → Glass.

Lock screen and screensaver

lock_background (wallpaper colour blur), lock_blur (0–64), lock_dim (0–100 %), lock_accent.

screensaver (on off), screensaver_timeout (idle seconds), screensaver_interval (5–600 s per slide), screensaver_dir, screensaver_lock (does dismissing it need the password).

Panels

ctlpanel_close, taskmgr_close and calc_close each take window, clickoff or button.

Window: drag it by the header, click elsewhere freely. Clickoff: it closes the moment you click away. Esc always closes.

The desktop

desktop_icons, desktop_icon_arrange (name type date size), welcome_at_startup, start_overlay, cat + cat_breed, widget_clock_face (minimal classic roman neon), notif_dnd and theme (one of the fifteen).

The font is one setting, and it is not in this file. Family, point size and text scale live in ~/.config/synui/font.state, which the compositor, the bar, synfiles, syn-settings, syn-disks, syn-update, syn-arsenal and synpkg all read. Set it from the font picker, from Control panel ▸ Appearance, or with synui-apply-font; whichever you use, the whole desktop moves together.

⛔ ui_font = was synui's own copy of the family and is obsolete and ignored as of 0.1.0-472 — it logs a line saying so. It was a second place the font was declared, and it won at the next config load, so a font changed from any other window in the suite moved every application and left the compositor's own dock, panels and window titles on the old face.

CRT effects

effects = on|off is the master switch. Then effect_scanline, effect_curvature, effect_aberration, effect_bloom, effect_glitch, effect_phosphor (off amber green white), effect_mono (blend toward that tint — bloom only bites once this is up), effect_hue and effect_lift.

Full write-up: Window Effects.

The AI

ai_layout — let the AI decide where a new window goes. ai_ctx_decor — tint a window's border while the AI holds context for it.

Power and the lid

Key
power_enabled	the master switch
power_dim_timeout	idle seconds before the screen dims
power_blank_timeout	…before it blanks
power_lock_timeout	…before it locks. 0 is never, which is what the live ISO sets
power_suspend_timeout	…before it suspends
power_lock_cmd power_suspend_cmd	what those two run
lid_close_action	on battery
lid_close_ac_action	on mains
lid_close_docked_action	with an external monitor attached

Each timeout is measured from the last input event, so they are independent rather than cumulative. Super+P edits them live and writes power.state, which then overrides these lines — delete that file to hand control back to synuirc.

Alt-Tab

alt_tab_style, alt_tab_preview, alt_tab_minimized (does the switcher include minimized windows) and alt_tab_all_desktops (does it reach past this workspace).

Game mode

Detection, and what gets stood down while a game is running.

Key
game_mode	the master switch
game_exclude	space-separated app_ids that are not games — replaces the built-in list. This is what stops a fullscreen Firefox video suspending the AI
game_include	Wayland-native app_ids that are games; also replaces. An allow-list, because "any fullscreen Wayland client" would make every fullscreen video a game
game_output	primary focused ask — which monitor a detected game is put on
game_suspend_ai game_stop_bar game_pause_wallpaper game_quiet_kmod game_drop_effects game_inhibit_idle	what to stand down
game_ai_stop_cmd / game_ai_start_cmd	and the command pairs that do it
game_bar_stop_cmd / game_bar_start_cmd
game_wp_stop_cmd / game_wp_start_cmd
game_kmod_quiet_cmd / game_kmod_restore_cmd

⚠ Change one of a pair and you must change the other. These are fire-and-forget: a stop that works paired with a start that does not leaves the desktop in the half-state and says nothing. game_ai_* also needs its /etc/sudoers.d grant to match the whole command line — synapd is a system unit, so a plain systemctl stop from the session user is bounced by polkit, invisibly.

More on all of it: Gaming.

Odds and ends

launcher_style (text logo — the start button), start_menu_style (menu app-overlay rofi), lock_fingerprint, bar_icon_theme, record_audio, record_edit, news_source and news_refresh.

Wallpaper, per monitor

wallpaper_output = DP-1 matrix
wallpaper_output_mode = DP-1 fit

Same token vocabulary as the global wallpaper / wallpaper_mode, so there is one thing to learn. Lines are read in order, and an override inherits whatever the global keys hold when it is first named.

Commands synui shells out to

terminal, about_cmd, network_cmd, bar_start_cmd / bar_stop_cmd, and game mode's game_bar_*, game_wp_*, game_kmod_*, game_ai_* pairs.

⚠ Each pair must match. These are fire-and-forget, so a stop that works paired with a start that does not leaves the desktop in the half-state and says nothing.

Keys

bind = super+Return term and unbind = super+Return. tap_key is which modifier opens the start menu when tapped alone (super ctrl alt shift none) and tap_action is what it opens. autostart = synui-bar, repeated for more than one.

⛔ super_space is obsolete and ignored, with a line in the journal saying so. Rebind it in the palette (Super+/, then F2).

Every shipped shortcut: Keybindings.

Read here, acted on by the bar

A few keys are parsed by the compositor and consumed by quickshell, so that each has one spelling and one clamp: bar_enabled, bar_shell, bar_edge, bar_opacity, bar_shape, dock_opacity, widget_glass, widget_clock_face.

See also

• The Desktop · The Dock · Keybindings
• Settings — the control panel, which writes most of this for you