Dock

A standalone application dock that displays pinned and running apps. Disabled by default.

[dock]enabled = false # set true to activateposition = "bottom" # top | bottom | left | rightactive_monitor_only = false # when true, only show apps/windows from the active monitormonitors = [] # connector names to show on; empty = all outputs
icon_size = 48main_axis_padding = 16 # inner padding along the icon row (main axis)cross_axis_padding = 8 # inner padding perpendicular to the icon rowitem_spacing = 6 # gap between items in pixelsbackground_opacity = 0.88shadow = true # cast the global [shell.shadow]radius = 16radius_top_left = 16 # optional per-corner overridesradius_top_right = 16radius_bottom_left = 16radius_bottom_right = 16concave_edge_corners = true # carve the screen-edge corners inward; requires margin_edge = 0margin_ends = 0 # inset from each end of the dock along its main axismargin_edge = 0 # distance from the nearest screen edge (positive values float the dock)
show_running = true # also show running apps not in the pinned listauto_hide = false # fade out when pointer leaves; fade in on approachreserve_space = true # reserve compositor exclusive zone / push windows away
active_scale = 1.0 # icon scale for the focused app (clamped 0.1–1.75)inactive_scale = 0.85 # icon scale for non-focused apps (clamped 0.1–1.0)magnification = true # magnify icons near the pointer (macOS-style)magnification_scale = 1.35 # max scale multiplier at the pointer center (1.0–2.0; 1.0 = off)active_opacity = 1.0inactive_opacity = 0.85show_instance_count = true # badge with window count when an app has 2+ windowsshow_dots = false # running-window indicator dots below app icons
launcher_position = "none" # none | start | end - optional launcher button on the docklauncher_icon = "grid-dots" # Tabler glyph for the launcher buttonlauncher_custom_image = "" # image path; overrides launcher_icon when setlauncher_custom_image_colorize = false # tint the custom image with the icon color
# Desktop entry IDs, StartupWMClass, or human-readable namespinned = ["firefox", "code", "kitty"]

radius sets all four corners at once. Any radius_* key overrides just that corner.

concave_edge_corners = true inverts the two corners on the side that touches the screen edge, so the dock flares outward and blends into it. The corner radii still control the curve size. Only applies when the dock actually touches the edge (margin_edge = 0).

Shadow blur, offset, and alpha are global under [shell.shadow]. The dock only exposes shadow = true|false.

`pinned` matching

Section titled “pinned matching”

Each entry in pinned is matched against desktop entries using these rules in order:

Desktop entry ID stem ("firefox" matches firefox.desktop and org.mozilla.Firefox.desktop)
StartupWMClass field of the desktop entry
App Name field (case-insensitive)
Full desktop entry path

If no match is found, a placeholder slot is reserved so the dock position is preserved.

Icon colorization

Section titled “Icon colorization”

Dock application icons follow the global [shell.app_icon_colorize] / [shell.app_icon_color] settings (see Shell → App icon colorization).

Configure in Settings → Appearance → Interface , or under [shell] in the Noctalia TOML config stack.

Active app emphasis

Section titled “Active app emphasis”

The focused app uses active_scale and active_opacity.
All other apps use inactive_scale and inactive_opacity.
Focus changes animate smoothly between the two states.

Magnification

Section titled “Magnification”

When magnification = true (default), icons grow as the pointer moves along the dock - similar to the macOS dock. Icons under the pointer grow the most; nearby entries scale down smoothly with distance.

magnification_scale sets the maximum multiplier at the pointer center (default 1.35, range 1.0–2.0). At 1.0, magnification is disabled even when magnification is on.
Magnification applies on top of active_scale / inactive_scale.
Icons may extend past the dock capsule into a small cross-axis pad (macOS-style); the background slab stays fixed size.
The launcher button participates when shown.
Hovering an entry shows a tooltip with its app name (launcher button shows Launcher ).

Auto-hide

Section titled “Auto-hide”

When auto_hide = true, the dock fades out after the pointer leaves and fades back in when the pointer enters the thin edge trigger strip.

reserve_space controls whether the dock keeps a compositor exclusive zone. With auto_hide = false, reserve_space = true keeps windows pushed away; reserve_space = false overlays the dock on top of full-screen clients. With auto_hide = true, reserve_space = false retracts the dock as an overlay (no gap); reserve_space = true keeps the gap while the dock slides out of view.

Section titled “Related IPC”

For dock visibility and reload commands, see Surfaces → Dock.