Dock

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

[dock]
enabled             = false      # set true to activate
position            = "bottom"   # top | bottom | left | right
active_monitor_only = false      # when true, only show apps/windows from the active monitor
monitors            = []         # connector names to show on; empty = all outputs

icon_size           = 48
main_axis_padding   = 16          # inner padding along the icon row (main axis)
cross_axis_padding  = 8           # inner padding perpendicular to the icon row
item_spacing        = 6          # gap between items in pixels
background_opacity  = 0.88
shadow              = true       # cast the global [shell.shadow]
radius              = 16
radius_top_left     = 16         # optional per-corner overrides
radius_top_right    = 16
radius_bottom_left  = 16
radius_bottom_right = 16
concave_edge_corners = true      # carve the screen-edge corners inward; requires margin_edge = 0
margin_ends         = 0          # inset from each end of the dock along its main axis
margin_edge         = 0          # distance from the nearest screen edge (positive values float the dock)

show_running        = true       # also show running apps not in the pinned list
auto_hide           = false      # fade out when pointer leaves; fade in on approach
reserve_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.0
inactive_opacity    = 0.85
show_instance_count = true       # badge with window count when an app has 2+ windows
show_dots           = false      # running-window indicator dots below app icons

launcher_position   = "none"     # none | start | end - optional launcher button on the dock
launcher_icon       = "grid-dots" # Tabler glyph for the launcher button
launcher_custom_image          = ""    # image path; overrides launcher_icon when set
launcher_custom_image_colorize = false # tint the custom image with the icon color

# Desktop entry IDs, StartupWMClass, or human-readable names
pinned = ["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

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

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

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

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

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.

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