Bar

Bar

Bars are defined as named subtables under [bar.*]. Each bar is spawned on every connected output, then per-monitor overrides are applied.

[bar]
order = ["main"]              # layer-shell creation order

[bar.main]
position           = "top"       # top | bottom | left | right
enabled            = true
auto_hide          = false       # slide out after pointer leaves; reveal from edge trigger strip
reserve_space      = true        # reserve compositor exclusive zone / push windows away

thickness          = 34          # bar cross-axis size in pixels (height for horizontal, width for vertical)
background_opacity = 1.0         # 0.0 (transparent) to 1.0 (opaque)
shadow             = true        # cast the global [shell.shadow]
contact_shadow     = false       # dark gradient between an attached panel and the bar (depth at the seam)
attach_panels      = true        # allow panels to attach to this bar (false = always float)
radius             = 12          # global corner radius fallback
radius_top_left    = 12
radius_top_right   = 12
radius_bottom_left = 12
radius_bottom_right = 12
margin_ends        = 180         # inset from each end of the bar along its main axis
margin_edge        = 10          # distance from the nearest screen edge (positive values float the bar)
padding            = 14          # main-axis padding from bar edges to start/end widget sections
widget_spacing     = 6           # gap between widgets within a section
scale              = 1.0         # content scale multiplier for icons and text

# Default capsule style for all widgets on this bar (see Widget Capsule section)
capsule            = false
capsule_fill       = "surface_variant"
capsule_radius     = 8.0            # omit for automatic pill radius
capsule_opacity    = 1.0
# capsule_border   = "outline"   # omit this key for no border by default

start  = ["launcher", "wallpaper", "workspaces"]
center = ["clock"]
end    = ["media", "tray", "notifications", "clipboard", "network", "bluetooth", "volume", "brightness", "battery", "control-center", "session"]

Radius precedence: radius is the global fallback; per-corner values override it when provided.

Multiple [bar.*] entries are supported — each is independently configured and rendered on all outputs.

[bar].order controls the order Noctalia creates bar layer-shell surfaces. This matters only for bars with reserve_space = true, and the compositor still owns the final exclusive-zone arrangement. Names omitted from order are appended after the listed names.

---

Per-monitor overrides

Inside a bar, add named monitor subtables under [bar.<name>.monitor.*]. First match wins, in file order.

[bar.main.monitor.dp1]
match              = "DP-1"    # connector name or description substring
enabled            = true
thickness          = 44
background_opacity = 0.9
radius             = 0
radius_top_left    = 12
radius_top_right   = 12
radius_bottom_left = 0
radius_bottom_right = 0
padding            = 20
widget_spacing     = 6
start              = []
center             = ["workspaces"]
end                = ["volume", "clock"]

match resolution — compared against:

1. Exact connector name (eDP-1, DP-1, HDMI-A-1, …)
2. Any substring of the monitor description string ("LG", "4K", "DELL", …)

match defaults to the subtable key name when omitted, so [bar.main.monitor."DP-1"] without a match field works too.

Only the fields you specify are overridden; everything else falls through to the [bar.*] defaults. Supported override fields: all bar fields, plus auto_hide, reserve_space, attach_panels, scale, background_opacity, color, and all capsule_* keys.

Shadow blur, offset, and alpha are global under [shell.shadow]. Bars only expose shadow = true|false.

contact_shadow = true adds a dark gradient at the seam between an attached panel and the bar, giving the panel a slight lifted-off-the-bar feel. It is independent of shadow and only takes effect on attached panels; the change applies on the next panel open.

---

Auto-hide

When auto_hide = true, the bar:

• Slides out once the pointer leaves the bar.
• Slides back in when the pointer reaches the matching screen edge trigger strip.

reserve_space = true reserves compositor exclusive zone and pushes windows away. Set it to false for overlay behavior; overlay bars do not reserve space and do not ask to be moved away from other exclusive zones. This applies whether auto_hide is enabled or disabled.

---

Widget Capsule

Each widget can have a capsule (pill-shaped background + optional border). Settings cascade from bar defaults down to per-widget overrides.

Bar-level defaults

Set under [bar.<name>] or [bar.<name>.monitor.*]:

Setting	Type	Default	Description
capsule	bool	false	true gives every widget a capsule unless [widget.*] sets capsule = false.
color	string	(unset)	Default icon + label color role or hex color for every widget on this bar.
capsule_groups	array of string	[]	Managed capsule group names for nearby widgets on this bar.
capsule_fill	string	surface_variant	Default capsule background color role or hex color.
capsule_foreground	string	(unset)	Default icon + label color role or hex color for capped widgets.
capsule_padding	number	6	Inner padding in logical pixels before scale is applied (clamped 0–48).
capsule_radius	number	(auto pill)	Default capsule corner radius in logical pixels before scale is applied (clamped 0–80). Omit to use automatic pill radius.
capsule_opacity	number	1.0	Capsule background opacity (0.0–1.0).
capsule_border	string	(omitted)	Color role or hex color for the capsule border. If omitted, no border by default. If present as "", no border.

Per-widget overrides

Set under [widget.<name>]:

Setting	Type	Default	Description
capsule	bool	(from bar)	Omit to inherit bar flag; false disables; true forces on.
capsule_group	string	(unset)	Select one of the bar’s managed capsule group names. Nearby widgets in the same section with the same non-empty value and matching capsule styling share one capsule.
capsule_fill	string	(from bar)	Capsule background color role or hex color.
capsule_foreground	string	(from bar)	Icon + label color role or hex color when capsule is visible. color takes priority over this.
capsule_padding	number	(from bar)	Per-widget inner padding (0–48).
capsule_radius	number	(from bar)	Per-widget corner radius (0–80). Omit to inherit; omit at every level for automatic pill radius.
capsule_opacity	number	(from bar)	Per-widget capsule background opacity.
capsule_border	string	(from bar)	Color role or hex color for the capsule border. Omit to inherit bar policy. Present but empty/whitespace-only = no border.
color	string	(unset)	Icon + label color role or hex color with or without capsule. Resolution order: color → capsule_foreground → built-in defaults.

Color role names use snake_case (e.g. on_surface, surface_variant, secondary). Hex colors may use #RGB, #RGBA, #RRGGBB, or #RRGGBBAA.

The capsule is hidden automatically when a widget reports no visible ink (empty tray, absent battery, invisible root). Subclasses may override Widget::shouldShowBarCapsule(). The taskbar also reuses its resolved capsule_radius for workspace group capsules when group_by_workspace = true, even if the taskbar’s outer widget capsule is disabled.

[bar.main]
capsule         = true
capsule_groups  = ["status", "media"]
capsule_fill    = "surface_variant"
capsule_opacity = 0.9
capsule_border  = "outline"

# Accent bar: primary fill + matching text
[bar.accent]
capsule            = true
capsule_fill       = "primary"
capsule_foreground = "on_primary"
capsule_padding    = 10
capsule_radius     = 8.0

[widget.volume]
capsule_fill   = "secondary"
capsule_radius = 0.0         # square this widget's capsule
capsule_border = ""          # no border on this widget

[widget.network]
capsule_group = "status"

[widget.bluetooth]
capsule_group = "status"

[widget.spacer]
type    = "spacer"
capsule = false