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

[widget.<name>]
type = "<widget-type>"   # defaults to <name> when omitted
scale = 1.0              # multiplies the owning bar's scale for this widget only
# ...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`

Displays the current time.

Setting	Type	Default	Description
`format`	string	`{:%H:%M}`	Clock format string for horizontal bars and vertical fallback. Use `\n` for multiple lines; examples: `{:%H:%M}\n{:%d/%m}`, `%H:%M`, `{:%-I:%M %p}`. See Date format tokens.
`vertical_format`	string	`""`	Format used when the bar is vertical. When empty, falls back to `format` with `:` replaced by line breaks. Supports the same syntax as `format`.
`tooltip_format`	string	`""`	Optional format shown when mouse is hovered over the clock widget. This utilizes the same date format tokens as format.

[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`

Empty space between widgets.

Setting	Type	Default	Description
`length`	number	`8`	Spacer length in screen pixels

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

`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.

Setting	Type	Default	Description
`display`	string	`"id"`	Label mode: `"none"`, `"id"`, or `"name"`. `"none"` is not available when `minimal = true`.
`minimal`	bool	`false`	Text-only labels (id/name) without pill backgrounds or slide animation.
`max_label_chars`	int	`1`	Maximum characters for workspace name labels; longer names are truncated. Only affects non-numeric labels (workspace IDs like `10`, `11` are never truncated).
`pill_scale`	float	`1.0`	Scale workspace pill thickness (cross-axis size; pill style only).
`active_pill_size`	float	`2.2`	Minimum active pill length along the bar, as a multiple of pill thickness. Labels may expand beyond this.
`inactive_pill_size`	float	`1.0`	Minimum inactive pill length along the bar, as a multiple of pill thickness. Labels may expand beyond this.
`focused_color`	string	`"primary"`	Color role or hex color for the focused workspace pill
`occupied_color`	string	`"secondary"`	Color role or hex color for occupied (non-focused) workspace pills
`empty_color`	string	`"secondary"`	Color role or hex color for empty workspace pills
`labels_only_when_occupied`	bool	`false`	Show id/name labels on workspaces with open windows and on the active workspace even when empty; other empty tags stay unlabeled. Requires `display = "id"` or `"name"`.
`hide_when_empty`	bool	`false`	Hide workspace pills with no open windows.

[widget.workspaces]
display = "id"          # none | id | name
minimal = false         # true = text-only labels, no animated pills
max_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 = true
pill_scale = 1.0
active_pill_size = 2.2
inactive_pill_size = 1.0
focused_color = "primary"
occupied_color = "secondary"
empty_color = "surface_variant"

`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.

Setting	Type	Default	Description
`group_by_workspace`	bool	`false`	Group icons into workspace capsules when per-window workspace assignment is available.
`show_all_outputs`	bool	`false`	Include windows from all monitors. With `group_by_workspace`, workspaces from every monitor are merged; capsule badges use `tag·n` (workspace tag, middle dot, monitor index in bar monitor order) when there is more than one monitor.
`only_active_workspace`	bool	`false`	Show only windows on the active workspace for each relevant monitor. Depends on compositor workspace data; if a window’s workspace cannot be resolved, it is still shown.
`show_workspace_label`	bool	`true`	When `group_by_workspace` is on, show the workspace tag pill on each capsule. Set `false` for groups without the label.
`workspace_label_placement`	string	`corner`	With grouping: `corner`, `centered` (on the pill edge), or `inside` (first tile in the pill). Requires `show_workspace_label`.
`hide_empty_workspaces`	bool	`false`	When `group_by_workspace` is on, do not show capsules for workspaces that have no windows in the taskbar list.
`workspace_group_capsule`	bool	`true`	Draw the background/border capsule around each workspace group. Set `false` for grouped icons and labels only.
`group_single_icon_per_app`	bool	`false`	With `group_by_workspace`, collapse multiple windows of the same app into one tile per workspace group. Left-click cycles that app’s windows; right-edge overlay dots indicate multiple windows.
`show_active_indicator`	bool	`true`	Show a small dot below the active window icon in the taskbar.
`active_opacity`	float	`1.0`	Opacity of the icon for the active (focused) window.
`inactive_opacity`	float	`1.0`	Opacity of icons for inactive (unfocused) windows.
`focused_color`	string	`"primary"`	Workspace disc fill when active (same roles as the workspaces widget)
`occupied_color`	string	`"secondary"`	Workspace disc fill when occupied
`empty_color`	string	`"secondary"`	Workspace disc fill when empty (shown at reduced opacity)

[widget.taskbar]
group_by_workspace = true
show_all_outputs = true
only_active_workspace = true
show_workspace_label = true
workspace_label_placement = "corner"
hide_empty_workspaces = true
workspace_group_capsule = true
group_single_icon_per_app = true
show_active_indicator = true
active_opacity = 1.0
inactive_opacity = 1.0
focused_color = "primary"
occupied_color = "secondary"
empty_color = "secondary"

`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).

Setting	Type	Default	Description
`min_length`	number	`80`	Minimum widget length in pixels
`max_length`	number	`260`	Maximum widget length in pixels
`icon_size`	number	`14`	Icon size in pixels
`title_scroll`	string	`"none"`	Title scrolling mode: `"none"`, `"always"`, or `"on_hover"`
`display`	string	`"icon_and_text"`	Content mode on horizontal bars: `"icon_and_text"`, `"icon_only"`, or `"text_only"`. Vertical bars show the icon only when a window is focused.
`show_empty_label`	bool	`false`	When enabled, show “No active window” instead of hiding the widget when no window is focused

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

`control-center`

Opens the control center panel on click.

Setting	Type	Default	Description
`glyph`	string	`"noctalia"`	Bar glyph name: Noctalia alias, Tabler icon name, or `U+` / `0x` codepoint
`custom_image`	string	`""`	Path to a custom image displayed instead of the glyph. Leave empty to use the glyph
`custom_image_colorize`	bool	`false`	When `true`, tint the custom image with the widget Color setting (same as the glyph fallback)

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

`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.

Setting	Type	Default	Description
`stat`	string	`"cpu_usage"`	Which stat to display (see table below)
`glyph`	string	`""`	Custom bar glyph name (Noctalia alias, Tabler icon name, or `U+` / `0x` codepoint). Leave empty to use the icon for the selected stat
`path`	string	`"/"`	Mount path for `disk_pct` (ignored otherwise)
`interface`	string	`""`	Network interface to monitor for `net_rx`/`net_tx`; empty uses the total across all non-loopback interfaces
`display`	string	`"gauge"`	`"gauge"` = icon + vertical fill bar; `"graph"` = icon + sparkline; `"text"` = icon + value
`highlight_color`	string	`"error"`	Color role (or fixed hex) the value tints toward as the stat rises past its activity/critical thresholds. See System Monitor.
`show_label`	bool	`true`	Show the text value next to the graph or gauge (always shown in `"text"` mode)
`label_min_width`	float	`0`	Minimum label width in pixels to prevent resizing as values change. Only relevant when `show_label` is enabled.

stat values:

Value	Display	Description
`cpu_usage`	`75%`	CPU utilisation (all cores)
`cpu_temp`	`65°C`	CPU package temperature
`gpu_temp`	`72°C`	GPU temperature
`gpu_vram`	`42%`	GPU VRAM usage
`ram_used`	`4.2 GiB`	RAM used (binary, auto-scaled)
`ram_pct`	`26%`	RAM used %
`swap_pct`	`12%`	Swap used %
`disk_pct`	`45%`	Disk used % for `path`
`net_rx`	`1.2 MB/s`	Network download speed (decimal, auto-scaled)
`net_tx`	`256 kB/s`	Network upload speed (decimal, auto-scaled)

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"

`volume`

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

Setting	Type	Default	Description
`device`	string	`"output"`	Audio target: `"output"` (default sink) or `"input"` (default source / microphone)
`scroll_step`	int	`5`	Percentage change applied on each mouse wheel step (1–25)
`show_label`	bool	`true`	Show the volume percentage next to the glyph (horizontal and vertical bars)
`mute_color`	string	`"error"`	Color role or hex color for the icon and label when muted

[widget.volume]
device = "output"   # output | input
scroll_step = 10
show_label = false
mute_color = "error"

[widget.input-volume]
type = "volume"
device = "input"

[widget.output-volume]
type = "volume"
device = "output"

IPC

# Output (speaker)
noctalia msg volume-set 65
noctalia msg volume-up
noctalia msg volume-up 10
noctalia msg volume-down
noctalia msg volume-mute

# Input (microphone)
noctalia msg mic-volume-set 0.5
noctalia msg mic-volume-up
noctalia msg mic-volume-up 5%
noctalia msg mic-volume-down
noctalia 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`

Horizontal audio spectrum using the current PipeWire monitor stream.

Setting	Type	Default	Description
`width`	number	`56`	Widget width in screen pixels
`bands`	number	`16`	Number of spectrum bands
`mirrored`	bool	`true`	Mirror the spectrum around the center line
`centered`	bool	`true`	Center bars on the cross axis instead of aligning them to the edge
`show_when_idle`	bool	`false`	Keep the widget visible even when no media is playing
`color_1`	string	`"primary"`	First gradient color role; fixed hex colors are also supported
`color_2`	string	`"primary"`	Second gradient color role; fixed hex colors are also supported

The widget height fills the available bar space automatically.

[widget.audio-vis]
type       = "audio_visualizer"
width      = 64
bands      = 20
centered   = true
show_when_idle = true
color_1 = "primary"
color_2 = "secondary"

`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.

Setting	Type	Default	Description
`album_art_only`	bool	`false`	Show only circular album artwork (horizontal bars; hidden in Settings on vertical bars)
`min_length`	number	`80`	Minimum widget length in pixels (hidden when `album_art_only` is enabled)
`max_length`	number	`220`	Maximum widget length in pixels (hidden when `album_art_only` is enabled)
`art_size`	number	`16`	Artwork size in pixels before scale
`title_scroll`	string	`"none"`	Media title scrolling mode: `"none"`, `"always"`, or `"on_hover"` (hidden when `album_art_only` is enabled)
`hide_when_no_media`	bool	`false`	Hide the widget when no MPRIS player is active

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

`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.

Setting	Type	Default	Description
`hide_inactive`	bool	`false`	Hide idle icons, and hide the whole widget when nothing is being captured
`icon_spacing`	number	`4`	Spacing between the indicator icons in pixels (0–48)
`active_color`	string	`"primary"`	Color role (or fixed hex) for an icon while that device is in use
`inactive_color`	string	`"outline"`	Color role (or fixed hex) for an idle icon (when `hide_inactive` is off)
`mic_filter_regex`	string	`""`	Regular expression matched against microphone app names; matches are ignored
`cam_filter_regex`	string	`""`	Regular expression matched against camera process names; matches are ignored

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  = true
icon_spacing   = 6
mic_filter_regex = "^(Firefox|easyeffects)$"

`battery`

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

Setting	Type	Default	Description
`display_mode`	string	`"icon"`	`"icon"` shows a glyph icon; `"graphic"` draws a rectangular battery shape with an animated fill level.
`show_label`	bool	`true`	In `icon` mode: show the percentage label next to the glyph. In `graphic` mode: overlay the percentage text on the battery body.
`device`	string	`"auto"`	UPower device selector. `auto` monitors the system power-supply battery only; explicit selectors can target any present battery-capable UPower device.
`warning_threshold`	integer	`20`	Battery percentage at or below which the widget switches to the warning color. `0` disables.
`warning_color`	color	`"error"`	Color applied when charge is at or below `warning_threshold`. Ignored while charging.

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`

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.

Setting	Type	Default	Description
`scroll_step`	int	`5`	Percentage change applied on each mouse wheel step (1–25)
`show_label`	bool	`true`	Show the brightness percentage next to the glyph (horizontal and vertical bars)

[widget.brightness]
scroll_step = 10
show_label = false

See [brightness] for backend configuration.

`bluetooth`

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

Setting	Type	Default	Description
`show_label`	bool	`false`	Show the connected device name next to the icon

[widget.bluetooth]
show_label = true

`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.

Setting	Type	Default	Description
`show_label`	bool	`true`	Show the SSID or interface name next to the glyph

[widget.network]
show_label = false

`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.

Setting	Type	Default	Description
`cycle_command`	string	`""`	Optional override command run on left click instead of compositor backend
`hide_when_single_layout`	bool	`false`	Hide the widget unless more than one keyboard layout is configured
`show_icon`	bool	`true`	Show the keyboard glyph
`glyph`	string	`"keyboard"`	Bar glyph name: Noctalia alias, Tabler icon name, or `U+` / `0x` codepoint. Shown only when `show_icon = true`
`show_label`	bool	`true`	Show the layout text label next to the keyboard glyph
`display`	string	`"short"`	`"short"` = compact code; `"full"` = full layout name. Ignored when `show_label = false`.
`custom_labels`	table	`{}`	Exact layout-name to label overrides. Matching labels override `display`; unmatched layouts still use `short` or `full`.

At least one of show_icon or show_label must be true.

[widget.keyboard_layout]
cycle_command = ""
hide_when_single_layout = false
show_icon = true
show_label = true
display = "short"   # short | full

[widget.keyboard_layout.custom_labels]
"German (Neo 2)" = "Neo2"
"English (US)" = "EN"

`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.

Setting	Type	Default	Description
`display`	string	`"short"`	`"short"` (`C N S`) or `"full"` (`Caps Num Scroll`)
`show_caps_lock`	bool	`true`	Show the Caps Lock indicator
`show_num_lock`	bool	`true`	Show the Num Lock indicator
`show_scroll_lock`	bool	`false`	Show the Scroll Lock indicator
`hide_when_off`	bool	`false`	Hide each indicator when it is off

[widget.lock_keys]
display          = "short"
show_caps_lock   = true
show_num_lock    = true
show_scroll_lock = false
hide_when_off    = false

`launcher`

Opens the launcher panel on click.

Setting	Type	Default	Description
`glyph`	string	`"search"`	Bar glyph name: Noctalia alias, Tabler icon name, or `U+` / `0x` codepoint
`custom_image`	string	`""`	Path to a custom image displayed instead of the glyph. Leave empty to use the glyph
`custom_image_colorize`	bool	`false`	When `true`, tint the custom image with the widget Color setting (same as the glyph fallback)

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

`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).

Setting	Type	Default	Description
`glyph`	string	`"clipboard"`	Bar glyph name: Noctalia alias, Tabler icon name, or `U+` / `0x` codepoint

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

noctalia msg clipboard-clear

`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.

Setting	Type	Default	Description
`glyph`	string	`"screenshot"`	Bar glyph name: Noctalia alias, Tabler icon name, or `U+` / `0x` codepoint
`primary_click`	string	`"region"`	Left-click action: `"region"` (interactive drag selection) or `"fullscreen"` (see below)

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

noctalia msg screenshot-region
noctalia msg screenshot-fullscreen
noctalia msg screenshot-fullscreen pick
noctalia msg screenshot-fullscreen DP-2
noctalia msg screenshot-fullscreen all
noctalia msg screenshot-region my-capture

Both commands use the global [shell.screenshot] output policy.

`screenshot-fullscreen` argument	Behavior
(none)	Focused monitor
`pick`	Display picker (multi-monitor); immediate capture on one monitor
`DP-2`, `HDMI-A-1`, …	Named output only—no picker; exact connector name or word-boundary match in the output description
`all` or `*`	One combined desktop PNG

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`

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

Setting	Type	Default	Description
`max_length`	number	`160`	Maximum length for the weather text
`show_condition`	bool	`true`	Show condition text like `Overcast` next to temperature

[widget.weather]
max_length     = 180
show_condition = false

`notifications`

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

Setting	Type	Default	Description
`hide_when_no_unread`	bool	`false`	Hide the widget when there are no unread notifications

[widget.notifications]
hide_when_no_unread = true

IPC

noctalia msg notification-dnd-toggle
noctalia msg notification-dnd-status
noctalia msg notification-clear-active
noctalia 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`

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).

Setting	Type	Default	Description
`hidden`	array of string	`[]`	Tray items to hide by id/name/bus/path token
`pinned`	array of string	`[]`	Tray items that always stay visible in the bar when `drawer = true`
`match_adjacent_spacing`	bool	`false`	Widen inline tray icon gaps to match the visual spacing of neighboring bar widgets (adds capsule padding on top of `widget_spacing`)
`drawer`	bool	`false`	Replace inline tray icons with a tray button that opens a tray drawer panel
`drawer_columns`	number	`3`	Number of tray icons per row in the drawer panel (`1` to `5`)

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

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

`power_profile`

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

No configurable settings.

`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

noctalia msg caffeine-enable
noctalia msg caffeine-disable
noctalia msg caffeine-toggle

`nightlight`

State	Icon	Meaning
Off	moon-off	Night light disabled
On	moon	Scheduled - follows `[location]` (`sunset`/`sunrise` or coordinates)
Forced	moon-stars	Always-on override - ignores schedule

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

noctalia msg nightlight-toggle
noctalia msg nightlight-force-toggle

`theme_mode`

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

No configurable settings.

IPC

noctalia msg theme-mode-toggle

`session`

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

Setting	Type	Default	Description
`glyph`	string	`"shutdown"`	Bar glyph name: Noctalia alias, Tabler icon name, or `U+` / `0x` codepoint

[widget.session]
glyph = "lock"

`wallpaper`

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

Setting	Type	Default	Description
`glyph`	string	`"wallpaper-selector"`	Bar glyph name: Noctalia alias, Tabler icon name, or `U+` / `0x` codepoint

[widget.wallpaper]
glyph = "photo"

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"