Widgets

Widget definitions are optional. When a name in a widget list matches a [widget.<name>] entry, that entry’s type and settings are used. When there is no match, the name itself is treated as the widget type with default settings.

Middle-click a bar widget to open Settings directly to that widget’s configuration.

[widget.<name>]
type = "<widget-type>"   # defaults to <name> when omitted
scale = 1.0              # multiplies all content by the owning bar's scale
font_scale = 1.0         # additional text-only multiplier
enabled = true           # show or hide this widget on the bar
custom_label = ""        # optional text shown with the widget; leave empty to hide it
show_glyph = true        # false hides the widget's icon glyphs
# ...widget-specific settings

This allows multiple named widgets with the same widget type:

[widget.clock-seconds]
type   = "clock"
format = "{:%H:%M:%S}"

[bar.default]
end = ["clock", "clock-seconds"]   # two clock widgets, different formats

Shared behavior and appearance

Configure click, scroll, and thumb-button bindings under Widget Actions. Configure shared capsule styling under Bar → Widget Capsule. Every bar widget, including plugin widgets, accepts custom_label, which renders as text next to the widget content (above it on vertical bars); widgets that manage their own identity, such as sysmon, render it inside their identity group. Set show_glyph = false on any widget, plugin widgets included, to hide its icon glyphs and reclaim the space they occupied; image content such as tray and taskbar icons is not affected. Widgets with no text of their own need custom_label to stay visible; battery instead hides its icon with display_mode = "none" (see Battery).

Peek

Widgets that show a glyph next to a value can hide the value until you hover them. With peek = true only the glyph is visible; hovering the widget slides the value out, and leaving collapses it again. Supported by volume, brightness, keyboard_layout, bluetooth, network, weather, battery (glyph display_mode), custom_button, sysmon (the gauge or graph slides out with the value), media (artwork reveals track text on horizontal bars), and tray (a tray glyph reveals inline icons when drawer mode is off). Media hides peek settings when album_art_only or hide_album_art is enabled.

[widget.volume]
peek           = true
glyph_position = "after"   # value sits before the glyph, so it opens toward the start
peek_delay_ms  = 250       # hover this long before revealing (default 100)

Setting	Type	Default	Description
`glyph_position`	string	`"before"`	`"before"` places the glyph before the value (left on top/bottom bars, above on left/right bars); `"after"` swaps them. Peek opens toward the value’s side
`peek`	bool	`false`	Show only the glyph; reveal the value while the widget is hovered. Ignored when the widget has no glyph or no value to show
`peek_delay_ms`	int	`100`	Hover time in milliseconds before the value starts to reveal, from `0` to `2000`. Same default as `accordion_delay_ms`; the reveal animates over 200 ms like `accordion_duration`, and collapsing is always immediate

Peek is independent of the capsule group accordion, which folds whole widgets instead of a single widget’s value.

Built-in widgets

Layout & windows

active_windowShows the active window icon and title for the current output.

clockDisplays the current time with configurable formats and timezone.

spacerAdds empty space or an optional interactive hot zone.

taskbarShows running and pinned applications, optionally grouped by workspace.

textShows fixed custom text on the bar.

workspacesSwitches workspaces with regular, minimal, or Focus Hint styles.

Audio, media & information

audio_visualizerDisplays a horizontal audio spectrum from the current PipeWire monitor stream.

mediaShows artwork and track details from the active MPRIS player.

volumeShows and controls PipeWire output or input volume.

weatherShows the current configured weather in the bar.

System & hardware

batteryShows battery charge level and state through UPower.

bluetoothShows Bluetooth adapter state and the connected device.

brightnessShows and adjusts the current monitor brightness.

keyboard_layoutShows the current keyboard layout and cycles layouts when supported.

lock_keysShows Caps Lock, Num Lock, and Scroll Lock state.

networkShows Wi-Fi, wired, and VPN status through NetworkManager.

power_profileShows and changes the current system power profile.

privacyShows microphone, camera, and screen capture activity.

sysmonShows one configurable system resource statistic.

trayShows StatusNotifierItem system tray icons.

Quick toggles

caffeineShows and controls the compositor idle inhibitor.

nightlightShows and controls scheduled or forced night light state.

theme_modeToggles between dark and light theme mode.

Buttons & panels

clipboardOpens the clipboard history panel from the bar.

control-centerOpens the control center panel from the bar.

custom_buttonShows a custom glyph, image, or label with bindable actions.

launcherOpens the launcher panel from the bar.

notificationsShows unread notifications and controls Do Not Disturb mode.

screenshotCaptures screen regions or displays through the bar.

sessionOpens the session menu panel from the bar.

settingsOpens the Noctalia Settings window from the bar.

wallpaperOpens the wallpaper picker panel from the bar.

Plugin widgets

Custom bar widgets are provided by plugins. A plugin’s bar-widget entry is referenced by its fully-qualified id; the plugin’s manifest declares any settings it exposes. See Plugins for installing, enabling, and authoring.

[widget.my_widget]
type = "<author>/<plugin>:<entry>"   # e.g. "noctalia/screen_recorder:recorder"