Widgets

Configure 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 the owning bar's scale for this widget only
enabled = true           # show or hide this widget on the bar
# ...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.

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"