Widgets

Widgets

Section titled “Widgets”

Widget definitions

Section titled “Widget definitions”

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. Disable [shell].middle_click_opens_widget_settings if you want middle-click to remain available to plugin widgets.

[widget.<name>]type = "<widget-type>" # defaults to <name> when omittedscale = 1.0 # multiplies the owning bar's scale for this widget onlyenabled = 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.main]end = ["clock", "clock-seconds"] # two clock widgets, different formats

clock

Section titled “clock”

Displays the current time.

[widget.clock]format = "{:%H:%M}\n{:%d/%m}"vertical_format = "{:%H\n%M}"tooltip_format = "{:%A, %B %d, %Y}"
[widget.clock-12h]type = "clock"format = "{:%-I:%M %p}"
[widget.clock-seconds]type = "clock"format = "{:%H:%M:%S}"vertical_format = "{:%H\n%M\n%S}"

spacer

Section titled “spacer”

Empty space between widgets.

[widget.gap]type = "spacer"length = 24

workspaces

Section titled “workspaces”

Workspace switcher with solid dots/pills and optional labels, or a minimal text-only style.

Workspace pills use the workspaces widget’s resolved capsule_radius. Set [widget.workspaces].capsule_radius for just the workspace switcher, or [bar.<name>].capsule_radius as the bar default. Pill styling and capsule_radius are ignored when minimal = true.

[widget.workspaces]display = "id" # none | id | nameminimal = false # true = text-only labels, no animated pillsmax_label_chars = 2 # truncate long workspace names (e.g. "VESKTOP" → "VE")labels_only_when_occupied = true # (1) (2*) ( ) (4) - occupied tags and the active tag show labels (*active but empty)hide_when_empty = truepill_scale = 1.0active_pill_size = 2.2inactive_pill_size = 1.0focused_color = "primary"occupied_color = "secondary"empty_color = "surface_variant"focused_output_only = false # true = only the focused monitor highlights its active workspace

taskbar

Section titled “taskbar”

Icon-only running application list. By default it follows the bar’s monitor (only windows the compositor associates with that monitor). Enable Show all monitors when you use one bar for everything but still want to see and focus apps on other monitors.

Application icons use global [shell.app_icon_colorize] when enabled (see Shell → App icon colorization).

Left-click an icon to focus that window. The active window shows a small primary dot under the icon. When grouped app collapsing is enabled, multi-window app tiles also show compact right-edge dots over the icon.

Only active workspace limits the list to windows the shell can place on a workspace that is currently active on its monitor (same idea as the v4 taskbar option). It works with or without group_by_workspace; with grouping, inactive workspace capsules are omitted.

Workspace grouping (group_by_workspace and related options) needs per-window workspace assignment from the compositor, not just a workspace list. Without it, the taskbar stays flat and those settings are hidden in the GUI (config keys are accepted but ignored). LabWC is a common example (discussion #2924); use the workspaces widget for switching there.

When group_by_workspace is enabled, workspace disc indicators (the small numbered/name tags) and optional group capsules (the background around each workspace’s icon row) use the taskbar widget’s resolved capsule_radius. Set [widget.taskbar].capsule_radius for just the taskbar, or [bar.<name>].capsule_radius as the bar default. Set show_workspace_label = false to hide workspace disc indicators (icons only). Set workspace_group_capsule = false to drop the group background/border while keeping grouping and disc labels.

[widget.taskbar]group_by_workspace = trueshow_all_outputs = trueonly_active_workspace = trueshow_workspace_label = trueworkspace_label_placement = "corner"hide_empty_workspaces = trueworkspace_group_capsule = truegroup_single_icon_per_app = trueshow_active_indicator = trueactive_opacity = 1.0inactive_opacity = 1.0focused_color = "primary"occupied_color = "secondary"empty_color = "secondary"focused_output_only = false # true = only the focused monitor highlights its active workspace

active_window

Section titled “active_window”

Shows the active window icon and title for the current output. The window icon uses global [shell.app_icon_colorize] when enabled (see Shell → App icon colorization).

[widget.active_window]min_length = 80max_length = 260icon_size = 14title_scroll = "on_hover"display = "icon_and_text"show_empty_label = true

control-center

Section titled “control-center”

Opens the control center panel on click.

[widget.control-center]custom_image = "/path/to/image.png"custom_image_colorize = true

sysmon

Section titled “sysmon”

System resource monitor. Shows an icon and value for one configurable stat. Multiple instances with different stats can coexist on the same bar. Sampling cadence is controlled globally by [system.monitor], not per widget. Hovering the widget shows the selected stat first, followed by the other currently available sysmon stats.

stat values:

For net_rx and net_tx, set interface to an exact kernel interface name from /proc/net/dev (for example wlan0 or enp5s0) to show only that interface. Leave it empty to show the total across all non-loopback interfaces.

GPU temperature is read from Linux hwmon when available, with an NVML fallback for NVIDIA proprietary drivers. GPU VRAM is read from AMDGPU DRM sysfs when available, with an NVML fallback for NVIDIA proprietary drivers.

[widget.cpu]type = "sysmon"stat = "cpu_usage"
[widget.cpu-graph]type = "sysmon"stat = "cpu_usage"display = "graph"show_label = false
[widget.temp]type = "sysmon"stat = "cpu_temp"
[widget.ram]type = "sysmon"stat = "ram_used"
[widget.disk]type = "sysmon"stat = "disk_pct"path = "/"
[widget.wifi-download]type = "sysmon"stat = "net_rx"interface = "wlan0"
[widget.wifi-upload]type = "sysmon"stat = "net_tx"network_speed_unit = "mb" # auto | kb | mbnetwork_speed_compact = true # show "1.2M" instead of "1.2 MB/s"

volume

Section titled “volume”

Shows PipeWire output (speaker) or input (microphone) volume and mute state.

[widget.volume]device = "output" # output | inputglyph = "" # custom active glyph; empty = built-in dynamic iconsmute_glyph = "" # custom mute/0% glyph; empty = built-in mute iconscroll_step = 10show_label = falsemute_color = "error"
[widget.input-volume]type = "volume"device = "input"
[widget.output-volume]type = "volume"device = "output"

IPC

Section titled “IPC”

Terminal window

# Output (speaker)noctalia msg volume-set 65noctalia msg volume-upnoctalia msg volume-up 10noctalia msg volume-downnoctalia msg volume-mute
# Input (microphone)noctalia msg mic-volume-set 0.5noctalia msg mic-volume-upnoctalia msg mic-volume-up 5%noctalia msg mic-volume-downnoctalia msg mic-mute

Volume and mic IPC use a default step of 5% when no explicit step is provided. Values and steps accept normalized (0.0–1.0) or percentage-style values (65, 65%, 5%). Rule of thumb: if you include a decimal and the value is <= 1.0, it is treated as normalized; otherwise it is treated as a percentage.

Output and mic volume are clamped to 0–100% by default. If [audio] enable_overdrive = true, the maximum is raised to 150%.

audio_visualizer

Section titled “audio_visualizer”

Horizontal audio spectrum using the current PipeWire monitor stream.

The widget height fills the available bar space automatically.

[widget.audio-vis]type = "audio_visualizer"width = 64bands = 20centered = trueshow_when_idle = truecolor_1 = "primary"color_2 = "secondary"

media

Section titled “media”

Shows the current media artwork and track title from MPRIS. On vertical bars (left / right), only the artwork is shown. On horizontal bars, enable album_art_only for the same compact look.

[widget.media]album_art_only = trueart_size = 24hide_when_no_media = true

privacy

Section titled “privacy”

Shows when your microphone, camera, or screen is being captured, based on PipeWire stream links. Each input type has its own icon that switches between an “off” glyph (idle) and an active glyph (in use). Hovering the widget lists the applications currently using each device.

The filters are useful for suppressing background services that hold a device open without actively recording. Leave them empty to report every capture.

[widget.privacy]type = "privacy"hide_inactive = trueicon_spacing = 6mic_filter_regex = "^(Firefox|easyeffects)$"

battery

Section titled “battery”

Shows battery charge level and state via UPower. Hides itself when the selected battery is missing or not present.

device = "auto" is safe on desktops: it will not use gamepads, mice, headsets, or other peripherals as the default battery widget. Use an explicit selector for those devices.

Selectors can be a full UPower object path, a native path/name, a stable suffix such as BAT0, or available device metadata such as model, serial, or vendor.

# Default system/laptop battery[widget.battery]type = "battery"device = "auto"
# Graphical battery with percentage overlay[widget.battery]type = "battery"display_mode = "graphic"
# Graphical battery without percentage text[widget.battery]type = "battery"display_mode = "graphic"show_label = false
# Internal battery by native name/suffix[widget.internal_battery]type = "battery"device = "BAT0"
# Second battery by full UPower object path[widget.second_battery]type = "battery"device = "/org/freedesktop/UPower/devices/battery_BAT1"
# Explicit peripheral battery[widget.gamepad_battery]type = "battery"device = "/org/freedesktop/UPower/devices/gaming_input_hid_001"

brightness

Section titled “brightness”

Shows the current monitor brightness level and adjusts it via scroll wheel. Hides itself when no controllable monitor is found. Click opens the display tab in the control center.

[widget.brightness]scroll_step = 10show_label = false

See [brightness] for backend configuration.

bluetooth

Section titled “bluetooth”

Shows the Bluetooth adapter state and connected device. Left-click opens the Bluetooth tab in the control center. Right-click toggles adapter power.

[widget.bluetooth]show_label = true

network

Section titled “network”

Shows the current network connection (Wi-Fi SSID and signal, or wired) via NetworkManager. Disconnected and disabled states use the appropriate status glyph without dimming the widget. Left-click opens the Network tab in the control center; right-click disables or reconnects the active Wi-Fi or wired connection.

[widget.network]show_label = false

keyboard_layout

Section titled “keyboard_layout”

Shows the current keyboard layout indicator from the active XKB state.

Left-click cycles layouts using the compositor backend when supported. Override with cycle_command for a custom shell command.

At least one of show_icon or show_label must be true.

[widget.keyboard_layout]cycle_command = ""hide_when_single_layout = falseshow_icon = trueshow_label = truedisplay = "short" # short | full
[widget.keyboard_layout.custom_labels]"German (Neo 2)" = "Neo2""English (US)" = "EN"

lock_keys

Section titled “lock_keys”

Shows Caps Lock / Num Lock / Scroll Lock state from the active XKB keyboard state.

Configuring this widget keeps lock-key state polling active even when [osd.kinds].lock_keys = false.

[widget.lock_keys]display = "short"show_caps_lock = trueshow_num_lock = trueshow_scroll_lock = falsehide_when_off = false

launcher

Section titled “launcher”

Opens the launcher panel on click.

[widget.launcher]glyph = "menu-2"custom_image_colorize = true

custom_button

Section titled “custom_button”

Shows a custom glyph/image, optional label, and runs configured shell commands.

[widget.quick-action]type = "custom_button"custom_image = "/path/to/icon.png"custom_image_colorize = truelabel = "Action"command = "notify-send Noctalia"

clipboard

Section titled “clipboard”

Shows a clipboard glyph and opens or closes the clipboard panel on click. History limits, clear/delete confirmation, auto-paste, and image actions are configured under [shell] - see Shell settings (clipboard_* keys).

[widget.clipboard]glyph = "clipboard-list"

Terminal window

noctalia msg clipboard-clear

screenshot

Section titled “screenshot”

Captures the screen through the compositor’s wlr-screencopy protocol (Niri, Hyprland, Sway, and other compositors that expose it). The widget is omitted from the bar when screencopy is unavailable.

The capture output policy (save to file, output directory, filename pattern, clipboard, freeze, pipe command) is global and lives under [shell.screenshot], shared by this widget and the IPC commands. The widget only sets its glyph and left-click action.

Click behavior:

• Left-click : runs primary_click (region or fullscreen) using the global output policy.
• Right-click : opens a menu with fullscreen and region capture.

Fullscreen on a single monitor captures that output immediately (focused monitor when using IPC with no argument). On multiple monitors , fullscreen opens a display picker : a top bar labeled “Choose display” with one button per connector (DP-1, HDMI-A-1, …). Click a button from any screen to capture that output - you do not need to move the pointer onto that monitor first. Clicking the dimmed desktop captures the monitor under the cursor (same as before). Press a [keybinds].cancel chord (default Escape ) to dismiss the picker.

Region mode shows a dimmed overlay; drag to select, release to capture. Press [keybinds].cancel to cancel. With freeze_screen = true, the shell captures each output first, then shows the frozen frame under the dim overlay while you select; the final PNG is cropped from that snapshot.

While dragging a region, a size badge (1920x1080) follows the pointer below the cursor.

[widget.screenshot]glyph = "screenshot"primary_click = "region"

IPC

Section titled “IPC”

Terminal window

noctalia msg screenshot-regionnoctalia msg screenshot-fullscreennoctalia msg screenshot-fullscreen picknoctalia msg screenshot-fullscreen DP-2noctalia msg screenshot-fullscreen all

Both commands use the global [shell.screenshot] output policy. The canonical command list is also under Keybinds & IPC → Media & UI → Screenshots.

The bar widget’s fullscreen action matches pick on multi-monitor setups. To capture a specific display from a script without UI, pass the connector name (for example noctalia msg screenshot-fullscreen DP-1).

weather

Section titled “weather”

Shows the current weather in the bar and opens the Weather control-center tab on click. Requires [weather] to be configured.

[widget.weather]max_length = 180show_condition = falseshow_temperature = false

notifications

Section titled “notifications”

Shows the pending notification count. Right-clicking toggles transient Do Not Disturb (DND) mode.

[widget.notifications]hide_when_no_unread = true

IPC

Section titled “IPC”

Terminal window

noctalia msg notification-dnd-togglenoctalia msg notification-dnd-statusnoctalia msg notification-clear-activenoctalia msg notification-clear-history

When DND is enabled, external incoming notifications are stored in history/control center but toast popups are suppressed. Internal Noctalia notifications are not stored in history.

tray

Section titled “tray”

System tray (StatusNotifierItem). Tray icons use the global [shell.app_icon_colorize] / [shell.app_icon_color] settings when enabled (see Shell → App icon colorization); [shell.app_icon_colorize] does not recolor symbolic tray icons. Symbolic/monochrome tray glyphs, the drawer chevron, and letter fallbacks follow the widget’s color / icon_color (items needing attention stay in the error color).

[widget.tray]hidden = ["nm-applet", "blueman", "org.kde.StatusNotifierItem-1-1"]pinned = ["nm-applet"]drawer = truedrawer_columns = 3drawer_item_size = 20

Tip: right-click a tray item and use Pin / Unpin in the item menu to update pinned without editing config manually.

power_profile

Section titled “power_profile”

Shows the current power profile using a glyph and cycles to the next available profile on click.

No configurable settings.

caffeine

Section titled “caffeine”

Shows a coffee glyph and toggles the compositor idle inhibitor on click. Uses the standard Wayland zwp_idle_inhibit_manager_v1 protocol.

No configurable settings.

IPC

Section titled “IPC”

Terminal window

noctalia msg caffeine-enablenoctalia msg caffeine-disablenoctalia msg caffeine-toggle

nightlight

Section titled “nightlight”

Click behavior:

• Left-click : toggles night light on/off. If currently forced, this drops the force override and lands on the regular scheduled-on state, so force is reversible without also turning night light off.
• Right-click : toggles the always-on (force) override.

User toggles made via the bar widget (or control center) are preserved across config hot-reload - only an actual change to enabled / force in your config file resets the corresponding override.

No configurable settings.

IPC

Section titled “IPC”

Terminal window

noctalia msg nightlight-togglenoctalia msg nightlight-force-toggle

theme_mode

Section titled “theme_mode”

Toggles between dark (moon glyph) and light (sun glyph) theme mode on click.

No configurable settings.

IPC

Section titled “IPC”

Terminal window

noctalia msg theme-mode-toggle

settings

Section titled “settings”

Shows a glyph/image and opens the Settings window on click.

[widget.settings]custom_image = "/path/to/settings.png"custom_image_colorize = true

session

Section titled “session”

Shows a power glyph and opens the session menu panel on click.

[widget.session]glyph = "lock"

wallpaper

Section titled “wallpaper”

Shows a glyph and opens the wallpaper picker panel on click.

[widget.wallpaper]glyph = "photo"

Plugin widgets

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