Skip to content
Noctalia Noctalia
FAQ

Dock

Dock

Section titled “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


icon_size           = 48
padding             = 8          # inner padding around the icon row (all sides)
item_spacing        = 6          # gap between items in pixels
background_opacity  = 0.88
shadow              = true       # cast the global [shell.shadow]
radius              = 16
margin_ends         = 0          # inset from each end of the dock along its main axis
margin_edge         = 8          # 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       = false      # keep exclusive zone even when auto-hidden


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)
active_opacity      = 1.0
inactive_opacity    = 0.85
show_instance_count = true       # badge with window count when an app has 2+ windows


# Desktop entry IDs, StartupWMClass, or human-readable names
pinned = ["firefox", "code", "kitty"]

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:

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

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

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.

Auto-hide

Section titled “Auto-hide”

When auto_hide = true, the dock:

  • Does not reserve compositor exclusive zone.
  • Fades out after the pointer leaves (slow ease-in animation).
  • Fades back in when the pointer enters the thin edge trigger strip.

Set reserve_space = true to keep the exclusive zone while auto-hidden.

IPC

Section titled “IPC”
Terminal window
noctalia msg show-dock       # re-display all instances
noctalia msg hide-dock       # close all instances until next reload
noctalia msg toggle-dock     # toggle dock visibility
noctalia msg reload-dock     # reload dock configuration