Shell

Shell settings
OSD
Lock screen
Keybinds

Shell settings

Global UI settings that apply across all shell surfaces.

[shell]
ui_scale              = 1.0             # content scale for panels and non-bar shell UI
font_family           = "sans-serif"    # Pango family string; Fontconfig handles fallback
lang                  = "en"            # override language detection; BCP-47 or POSIX locale
time_format           = "{:%H:%M}"      # default time format for shell UI without its own setting
date_format           = "%A, %x"        # default date format for shell UI without its own setting
offline_mode          = false           # block all outgoing HTTP requests
telemetry_enabled     = false           # anonymous startup ping
setup_wizard_enabled = true              # open first-run wizard while the marker is missing
niri_overview_type_to_launch_enabled = false # niri-only type-to-launch from overview
polkit_agent          = false           # register Noctalia's native polkit authentication agent
password_style        = "default"       # default | random
avatar_path           = "~/Pictures/avatar.png"
settings_show_advanced = false          # show advanced settings by default in Settings
middle_click_opens_widget_settings = true # middle-click bar widgets to open their Settings entry
show_location         = true            # show weather location text in shell UI
app_icon_colorize     = false           # recolor application icons across the shell
app_icon_color        = "on_surface"    # ColorSpec when colorize is enabled; see App icon colorization below
clipboard_enabled     = true            # false disables clipboard history/panel (basic copy & paste still work)
clipboard_history_max_entries = 100     # unpinned history cap (10–10000); pinned entries are exempt
clipboard_confirm_clear_history = true  # confirm before clear history / delete unpinned entries
clipboard_auto_paste  = "auto"          # off | auto | ctrl_v | ctrl_shift_v | shift_insert
clipboard_image_action_command = ""     # image clipboard action; e.g. "gimp {path}" or "satty -f -"
shared_gl_context     = true            # startup-only; share GPU textures across surfaces

[shell.animation]
enabled = true
speed   = 1.0   # 1.0 = normal, 0.5 = 2× slower, 2.0 = 2× faster

[shell.shadow]
direction = "down"  # center, up, down, left, right, up_left, up_right, down_left, down_right
alpha     = 0.55    # multiplied by each component's background opacity

[shell.panel]
transparency_mode     = "solid"  # solid | soft | glass; controls floating/centered opacity and card translucency
borders               = true   # outline on floating/centered panel shells and section cards inside panels
shadow                = true   # cast the global [shell.shadow] from panel surfaces
launcher_placement       = "centered" # attached | floating | centered
clipboard_placement      = "centered" # attached | floating | centered
control_center_placement = "attached" # attached | floating | centered
wallpaper_placement      = "attached" # attached | floating | centered
session_placement        = "attached" # attached | floating | centered
floating_offset          = 8           # px gap between a floating/detached panel and the bar edge
open_near_click_control_center = false  # attached/floating: follow the bar click instead of bar-center
open_near_click_launcher       = false  # attached/floating: follow the bar click instead of bar-center
launcher_categories            = true   # show launcher category filters; Tab toggles them while open
launcher_show_icons            = true   # show application icons in launcher results
launcher_compact               = false  # smaller icons and tighter rows; hides subtitles
launcher_session_search        = false  # include session actions in general search, not only behind /session
launcher_sort_by_usage         = true   # boost frequently used apps and show Recently Used filter
open_near_click_clipboard      = false  # attached/floating: follow the bar click instead of bar-center
open_near_click_wallpaper      = false  # attached/floating: follow the bar click instead of bar-center
open_near_click_session        = false  # attached/floating: follow the bar click instead of bar-center

[shell.screen_corners]
enabled = false    # overlay black rounded corners on each screen
size    = 32       # corner radius in logical pixels (1–100)

[shell.mpris]
blacklist = []           # optional list of players to hide from media widgets/control-center

[shell.screenshot]
save_to_file      = true                       # write captures as PNG to the output directory
directory         = ""                          # output folder; empty = ~/Pictures
filename_pattern  = "screenshot_%Y%m%d_%H%M%S"  # strftime pattern, no extension (.png is added)
copy_to_clipboard = false                       # also place the PNG on the clipboard
freeze_screen     = false                       # freeze the desktop before region selection
pipe_to_command   = false                       # pipe the PNG to a shell command on stdin
pipe_command      = ""                          # annotator/uploader, e.g. "swappy -f -" or "satty -f -"

Notes:

ui_scale is completely separate from bar.scale and [widget.*].scale: bar scale settings only affect bar widget content; ui_scale covers the control center, launcher, clipboard, and other non-bar surfaces. Neither changes Wayland output / HiDPI buffer scale.
font_family sets the primary Pango family for all shell text. Can be a concrete family like Inter or a generic like sans-serif.
time_format and date_format are fallbacks for shell-owned displays such as the home tab, calendar tab, and lock screen. Widget-specific clock formats still use their own widget settings. See Date format tokens.
offline_mode prevents the shell from making any outgoing HTTP requests (weather, community palettes, community templates, album art, remote notification icons). Distro packagers can default to true to comply with policies requiring explicit user consent for network access.
telemetry_enabled sends a single anonymous POST to api.noctalia.dev/ping on each startup containing: a random instance ID, shell version, compositor name, OS name, RAM, monitor resolutions, and UI scale. No personal data is collected. The instance ID is a random UUID stored in ~/.local/state/noctalia/instance.id.
setup_wizard_enabled: when false, Noctalia does not auto-open the setup wizard on startup even if .setup-complete is missing. Use this for declarative or preseeded deployments; the marker remains the normal completion state for interactive runs.
niri_overview_type_to_launch_enabled is opt-in. When true on niri, Noctalia keeps a tiny keyboard-focus layer surface while overview is open so typing a letter or number opens the launcher with that initial query. This gives up niri’s exact native handling for some overview-only keyboard state, such as the app focus ring.
polkit_agent controls registration on org.freedesktop.PolicyKit1. Keep disabled if another desktop agent handles auth prompts.
Notification daemon ownership moved out of [shell]: use [notification].enable_daemon in Services.
password_style: default uses circle-filled; random cycles through multiple filled glyph shapes on polkit and lock screen inputs.
settings_show_advanced: when true, Settings opens with advanced entries visible.
middle_click_opens_widget_settings: when true, middle-clicking a bar widget opens Settings directly to that widget’s configuration. Set it to false if a scripted widget needs onMiddleClick().
show_location: when false, weather location text/coordinates are hidden in shell surfaces.
app_icon_colorize and app_icon_color: global application icon tinting for the dock, system tray (bar and drawer), taskbar, active-window widget, and launcher panel results. See App icon colorization. Bar launcher / control-center widgets can optionally tint custom_image via custom_image_colorize using the widget Color setting (Presentation group in the widget editor).
lang: empty follows $LC_ALL, $LC_MESSAGES, then $LANG. Values may be BCP-47 tags (pt-BR, zh-Hans) or POSIX locale names (pt_BR.UTF-8, zh_CN.UTF-8). Chinese region locales infer script before matching catalogs, so zh_CN and zh_SG match zh-Hans, while zh_TW, zh_HK, and zh_MO match zh-Hant.
clipboard_enabled: when false, disables clipboard history only — the history is no longer recorded or persisted, and the clipboard panel and bar/control-center shortcuts are unavailable. The live clipboard transport stays active, so basic copy/cut/paste in text fields and launcher math/emoji copy-to-clipboard actions keep working.
clipboard_history_max_entries: caps how many unpinned clipboard history rows Noctalia keeps (default 100, range 10–10000). Pinned entries stay outside this limit. Lowering the value trims older unpinned rows on reload.
clipboard_confirm_clear_history: when true (default), the clipboard panel asks before Clear history and before deleting an unpinned entry (trash in the preview, or double-click a row). When false, those actions apply immediately: sidebar clear removes unpinned rows and keeps pins when any exist, or clears everything when nothing is pinned; unpinned single deletes are immediate. Pinned entries still require confirmation before delete. With confirmation enabled, the clear dialog only offers Keep pinned when both pinned and unpinned rows exist; if history is all pinned or all unpinned, the description matches that case. Toggle in Settings → Shell → Clipboard.
clipboard_auto_paste: auto = image entries use Ctrl+V, text entries use Ctrl+Shift+V; off = copy only, no automatic paste.
clipboard_image_action_command: when non-empty, image clipboard previews show an action button. Use {path} to receive an exported image file path. Use {stdin} (expanded to -) or omit {path} to receive the image bytes on stdin, matching the v4 annotation tool behavior (satty -f -, gradia, etc.).
shared_gl_context: when true (default), all rendering surfaces share a single EGL context group so wallpaper and icon textures are uploaded once in VRAM and reused across monitors. Set to false if you see corrupted textures (e.g. vertical stripe artifacts) on older GPUs with buggy cross-context texture sharing. Each surface then creates its own standalone context, which uses more VRAM on multi-monitor setups. Restart required.
shell.animation.enabled disables all animated transitions globally. speed scales durations globally.
shell.shadow defines the shared shadow style for shell surfaces and xdg-popup chrome such as panels, menus, pickers, and select dropdowns. direction controls which way the shadow is cast; blur is fixed at 12 px. Components such as panels, bars, and the dock only opt in/out with shadow = true|false.
shell.panel.transparency_mode controls panel glass styling. solid keeps cards opaque and floating/centered panels solid, soft makes floating/centered panels lightly translucent and cards subtly translucent, and glass makes both visibly translucent while clamping card opacity high enough for readable text. Attached panels continue to use the effective panel background opacity inherited from the host bar.
shell.panel.borders draws an outline on detached panel shells and on section cards inside panels (control center tabs, clipboard preview, setup wizard steps, etc.). Attached bar-merged panels stay borderless on the shell edge. Default is true; set to false for a flatter, borderless look.
shell.panel.shadow toggles the rendered drop shadow on attached, floating, and centered panels. Shadow direction and alpha come from [shell.shadow].
shell.panel.launcher_placement, clipboard_placement, control_center_placement, wallpaper_placement, and session_placement accept attached, floating, or centered. attached merges the panel with the host bar when the bar allows attach_panels; floating keeps the panel detached but near the bar; centered opens it in the middle of the monitor. Defaults are centered for Launcher and Clipboard, attached for Control Center, Wallpaper, and Session.
shell.panel.floating_offset sets the gap in pixels between a floating or detached panel and the bar edge (default 8). It applies to floating placement and to panels using the reserved edge area when multiple bars share an edge; attached and centered panels ignore it.
When multiple enabled bars resolve to the same edge on one monitor, exact source-bar attachment is ambiguous. In that case attached/floating panels use the compositor’s reserved edge area and open outside the bar stack instead of trying to merge with one bar.
shell.panel.open_near_click_control_center, open_near_click_launcher, open_near_click_clipboard, open_near_click_wallpaper, and open_near_click_session position attached or floating panels near the click location on the bar instead of centering them along the bar. They are ignored when the corresponding placement is centered.
shell.panel.launcher_categories shows compact category filters in the launcher for providers that expose categories, currently Applications and Emoji. All leaves results unfiltered. With a prefixed provider such as /emo, the filters come from that provider. Press Tab while the launcher is open to hide/show the filters; the left/right keybind actions move between filters.
shell.panel.launcher_show_icons toggles application icons in launcher result rows. Prefixed-provider rows (for example emoji) still show their leading character when icons are hidden.
shell.panel.launcher_compact uses smaller icons, tighter padding, and single-line rows (subtitles hidden).
shell.panel.launcher_sort_by_usage boosts frequently launched apps toward the top of results and exposes a Recently Used category filter. Disable it for strictly alphabetical ordering within each provider.
Reset stored launcher usage data from Settings → Panels → Launcher → Reset Usage Data (clears usage_counts.json and recently_used.json while Noctalia is running).
shell.panel.launcher_session_search surfaces session actions (lock, suspend, reboot, shutdown, logout) in the general launcher search once you type at least two characters, instead of only behind the /session prefix. Disabled by default.
shell.mpris.blacklist excludes matching MPRIS players from Noctalia media UI and active-player selection. Entries are case-insensitive and match player bus name, identity, desktop entry, or a bus-name substring token (for example "spotify").
shell.screenshot holds the global output policy for all screenshot captures (region, fullscreen), shared by the screenshot bar widget and the screenshot-region / screenshot-fullscreen IPC commands. At least one of save_to_file, copy_to_clipboard, or pipe_to_command must be enabled or the capture reports “No screenshot output enabled”. directory accepts ~; filename_pattern is a strftime pattern (the .png extension is appended). copy_to_clipboard requires clipboard integration (clipboard_enabled = true). pipe_command runs via /bin/sh -lc with the PNG written to its stdin — use it for annotators or uploaders (swappy -f -, satty -f -); for plain clipboard copies use copy_to_clipboard instead. The bar widget itself only configures its glyph and primary_click (region vs fullscreen). On multiple monitors, fullscreen from the bar (or screenshot-fullscreen pick) opens a display picker with one button per connector; scripts can skip the picker with noctalia msg screenshot-fullscreen DP-1 (connector name). Edit in Settings → Shell → Screenshot.
Window switcher is an Alt+Tab-style overlay with no [shell] settings yet. Bind your compositor shortcut to noctalia msg window-switcher (see Shell & UI → Window switcher). While open, windows appear in a centered grid (up to five columns) with application icons, titles, and a per-window close control. Tab / Shift+Tab cycle selection; arrow keys move within the grid; releasing Alt or Enter confirms; Escape cancels. The list updates live when windows open, close, or retitle while the overlay stays open.

App icon colorization

When app_icon_colorize = true, Noctalia recolors application bitmap icons (desktop/tray pixmaps and file-backed icons) so they follow the active palette:

Dock pinned and running app icons
Tray inline icons and the tray drawer panel
Taskbar window icons
Active window widget icon
Launcher panel search result app icons (same bake as taskbar)

Glyphs, symbolic tray icons, media album art, and other non-app-bitmap images are unchanged. Launcher panel result icons use the same app-icon bake as the taskbar.

app_icon_color is a color role or fixed hex color (#RGB, #RGBA, #RRGGBB, #RRGGBBAA), using the same picker as bar capsule colors. When omitted while colorize is enabled, Noctalia picks a theme-aware default: on_surface in light mode and on_surface_variant in dark mode.

Icons are desaturated on the CPU, contrast-normalized, then tinted. Changes apply immediately when you edit the setting in Settings → Appearance → Interface, switch light/dark mode, or change the palette.

Per-widget colorize_icons / icon_colorization keys on the dock or tray are no longer used — configure this only under [shell].

OSD

[osd]
position = "top_center"  # top_right | top_left | top_center | bottom_right | bottom_left | bottom_center | center_right | center_left
orientation = "horizontal" # horizontal | vertical
scale = 1.0              # OSD size multiplier on top of shell.ui_scale
# monitors = ["DP-1"]    # connector names; omit or leave empty for all monitors

[osd.kinds]
volume = true            # master volume OSD toggle
volume_output = true     # output (speaker) volume; requires volume = true
volume_input = true      # input (microphone) volume; requires volume = true
brightness = true        # display brightness
wifi = true              # Wi-Fi toggle
bluetooth = true         # Bluetooth toggle
power_profile = true     # power profile changes
caffeine = true          # idle inhibitor toggle
dnd = true               # Do Not Disturb toggle
lock_keys = true         # Caps/Num/Scroll Lock popups
keyboard_layout = true   # input keyboard layout changes

The OSD powers volume, brightness, DND, caffeine, lock-key, keyboard-layout, external/IPC Wi-Fi, external/IPC Bluetooth, and external/IPC power-profile popups, and defaults to top_center with a horizontal layout. Set orientation = "vertical" for a taller vertical gauge. scale multiplies the effective OSD size on top of shell.ui_scale (for example 1.25 makes volume, brightness, and lock-key popups 25% larger than the default). monitors limits OSD popups to the listed connector names (same matching rules as notification toasts and the dock); leave it empty to show on every connected output. If none of the configured monitors are connected, OSD falls back to all outputs until one reconnects. Each popup kind can be toggled independently under [osd.kinds]. The volume master toggle enables both output and input OSDs by default; set volume_output or volume_input to false to disable one side only. lock_keys = false disables Caps/Num/Scroll Lock popups; when no lock_keys bar widget is configured, this also stops lock-key state polling. keyboard_layout = false disables layout-change popups.

Lock screen

Set [lockscreen].enabled = false to turn off session lock entirely: no ext-session-lock-v1 engagement, no logind lock/unlock integration, and lock actions are hidden or no-op (idle lock, session panel, launcher, and noctalia msg session lock). lock-and-suspend falls back to suspend-only while the lock screen is disabled.

When enabled and wlr-screencopy is available, Noctalia can capture the desktop before the session lock engages and use that snapshot as the lock screen background instead of the wallpaper. Desktop capture is disabled by default.

Configure under [lockscreen] in TOML, or use Settings → Security → Lock Screen. The Desktop capture toggle appears only when your compositor supports screencopy. Use Wallpaper to pick a custom lock screen image (empty uses the desktop wallpaper per output).

[lockscreen]
enabled               = true      # master switch for session lock
allow_empty_password  = false     # submit Enter with an empty password (security-key PAM stacks)
blurred_desktop       = false     # use a desktop snapshot as the lock screen background
blur_intensity        = 0.5       # background blur (0.0 = none, 1.0 = maximum)
tint_intensity        = 0.3       # surface-color tint over the background (0.0 = none, 1.0 = opaque)
wallpaper             = ""        # optional image path; empty uses the desktop wallpaper per output

Field	Type	Default	Description
`enabled`	bool	`true`	Master switch for session lock, logind integration, and lock actions.
`allow_empty_password`	bool	`false`	When `true`, Enter can submit an empty password (needed for some security-key PAM stacks). When `false`, empty submits are ignored to avoid accidental `pam_faillock` lockouts from wake keys.
`blurred_desktop`	bool	`false`	Capture each output before lock and use it as the lock screen background.
`blur_intensity`	float	`0.5`	Blur strength for the active lock screen background (`0.0`–`1.0`).
`tint_intensity`	float	`0.3`	Surface-color tint over the active lock screen background (`0.0`–`1.0`).
`wallpaper`	string	`""`	Optional image path for the lock screen. When empty, each output uses its desktop wallpaper. Ignored when desktop capture is active.

If capture fails (missing protocol, permission denied, etc.), the lock screen falls back to the normal per-output wallpaper. The snapshot lives in memory only until unlock. Blur and tint sliders can be adjusted live from Settings while the session is locked.

Keybinds

Centralized keyboard actions for shell panels (launcher, session, clipboard, wallpaper), panel close/cancel, and dismissing interactive region screenshot selection (including while freeze_screen pre-capture is in progress).

[keybinds]
validate = ["return", "kp_enter"]
cancel   = ["escape"]
left     = ["left"]
right    = ["right"]
up       = ["up"]
down     = ["down"]

Each action accepts a single string chord or an array of chords.

Chord format: key, modifier+key, or modifier+modifier+key

Supported modifiers: ctrl, shift, alt

super bindings are rejected (super, win, windows, logo, meta, mod4) and produce a config parse error.

Supported actions: validate, cancel, left, right, up, down

Recording from the GUI

Open Settings → Keybinds to bind chords interactively. Each action shows the current chord(s) and a trailing slot reading “Click to add keybind”.

Click a slot, then press the key combination. The recorder previews held modifiers (e.g. Ctrl + Shift + …) and commits as soon as a non-modifier key is pressed.
Press a modifier-only chord (no regular key) and click away to abort the recording without changing the binding.
Pressing Super / Windows - either alone or as a modifier - cancels the recording and surfaces a transient toast explaining that compositor-reserved keys cannot be bound. Click the slot again to retry with a different chord.
Use the × next to a row to remove that specific binding. Removing every binding falls back to the value from your TOML config, or the built-in default if none is set.

Chords recorded in the GUI are serialized as ctrl+shift+Return-style strings under [keybinds] in ~/.local/state/noctalia/settings.toml and follow the same parsing rules as hand-written config.

Session panel

The session (power) menu opened from the bar Session widget or Control Center lists Lock, Log out, Lock & Suspend, Reboot, and Shut down by default. The launcher also exposes the same enabled entries under /session. Log out uses compositor-native exits where available, including LabWC’s labwc --exit. You can change which buttons appear, their order, whether each is enabled, and optionally replace the implementation with a shell command (still run after logging_out / rebooting / shutting_down hooks when the action is one of those three).

Built-in suspend/reboot/shutdown actions resolve from prioritized backend lists (systemd/logind first, then distro/runtime fallbacks) and cache the working backend in-memory for the current session. Override each built-in action globally under [shell.session.power] when auto-detection is not enough:

[shell.session.power]
suspend = "sudo -n zzz"
reboot = "sudo -n reboot"
shutdown = "sudo -n poweroff"

When an override is set, Noctalia runs that command for the built-in suspend/reboot/shutdown actions (session panel, launcher, IPC, and idle). Per-row command still overrides a single menu button when you need one-off behavior.

Configure under [shell.session] in TOML, or use Settings → Power → Session menu: entries, reorder, and Show are listed inline; use the settings (cog) control on a row for behavior, label, command, icon, shortcut, and style. Add action appends a custom-command entry by default. The default five actions are assigned keyboard shortcuts 1–5; pressing the key while the panel is open triggers the action immediately.

Field	Type	Default	Description
`action`	string	required	`lock`, `logout`, `suspend`, `lock_and_suspend`, `reboot`, `shutdown`, or `command` (custom entry).
`enabled`	bool	`true`	When `false`, the button is hidden.
`command`	string	unset	Optional. If set, the string is run with `/bin/sh -c` instead of the built-in handler. For `action = "command"`, this field is required.
`label`	string	unset	Optional button label (otherwise translated defaults).
`glyph`	string	unset	Optional bar-style icon id (otherwise defaults per action). Under Session menu in Settings → Power, open a row’s settings (cog) editor and use the icon preview to pick a glyph.
`shortcut`	string	`"1"`–`"5"`	Optional keyboard shortcut that triggers the action while the session panel is open. Any XKB key name (e.g. `1`, `F1`, `Escape`) or modifier combo (`Ctrl+1`). Clear to disable.
`destructive`	bool	`false`	Use the destructive (warning) button style.

Omitting [[shell.session.actions]] entirely keeps the default five actions. To define your own list, declare one or more tables. An explicit empty array hides all session buttons:

[shell.session]
actions = []

# Example: reorder, disable reboot, custom suspend, override lock
[[shell.session.actions]]
action = "lock"
command = "swaylock -f"

[[shell.session.actions]]
action = "logout"
enabled = true

[[shell.session.actions]]
action = "command"
label = "Sleep"
glyph = "bedtime"
command = "systemctl suspend"

[[shell.session.actions]]
action = "shutdown"
destructive = true