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
# ...widget-specific settings

This allows multiple instances of 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`.

[widget.clock]
format = "{:%H:%M}\n{:%d/%m}"
vertical_format = "{:%H\n%M}"

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

Setting	Type	Default	Description
`display`	string	`"id"`	Label mode: `"none"`, `"id"`, or `"name"`
`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

[widget.workspaces]
display = "id"   # none | id | name
focused_color = "primary"
occupied_color = "secondary"
empty_color = "surface_variant"

`taskbar`

Icon-only running application list. By default it follows the bar’s output (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 displays.

Left-click an icon to focus that window. The active window shows a small primary dot under the icon.

When group_by_workspace is enabled, workspace group capsules 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.

Setting	Type	Default	Description
`group_by_workspace`	bool	`false`	Group icons into workspace capsules when backend workspace-app mapping is available.
`show_all_outputs`	bool	`false`	Include windows from all displays. With `group_by_workspace`, workspaces from every monitor are merged; capsule badges use `tag·n` (workspace tag, middle dot, monitor index in bar output order) when there is more than one output.

[widget.taskbar]
group_by_workspace = true
show_all_outputs = true

`active_window`

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

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

[widget.active_window]
min_length = 80
max_length = 260
icon_size = 14
title_scroll = "on_hover"

`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

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

`sysmon`

System resource monitor. Shows an icon and value for one configurable stat. Multiple instances with different stats can coexist on the same bar.

Setting	Type	Default	Description
`stat`	string	`"cpu_usage"`	Which stat to display (see table below)
`path`	string	`"/"`	Mount path for `disk_pct` (ignored otherwise)
`display`	string	`"gauge"`	`"gauge"` = icon + vertical fill bar; `"graph"` = icon + sparkline; `"text"` = icon + value
`show_label`	bool	`true`	Show the text value next to the graph or gauge (always shown in `"text"` mode)

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
`ram_used`	`4.2G`	RAM used (human-readable)
`ram_pct`	`26%`	RAM used %
`swap_pct`	`12%`	Swap used %
`disk_pct`	`45%`	Disk used % for `path`
`net_rx`	`1.2M`	Network download speed (auto-scaled)
`net_tx`	`256K`	Network upload speed (auto-scaled)

[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 = "/"

`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)
`show_label`	bool	`true`	Show the volume percentage next to the glyph (horizontal and vertical bars)

[widget.volume]
device = "output"   # output | input
show_label = false

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

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

IPC

# Output (speaker)
noctalia msg set-volume 65
noctalia msg raise-volume
noctalia msg raise-volume 10
noctalia msg lower-volume
noctalia msg mute

# Input (microphone)
noctalia msg set-mic-volume 0.5
noctalia msg raise-mic-volume
noctalia msg raise-mic-volume 5%
noctalia msg lower-mic-volume
noctalia msg mute-mic

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
`show_when_idle`	bool	`false`	Keep the widget visible even when no media is playing
`low_color`	string	`"primary"`	Color role or hex color for the first bars
`high_color`	string	`"primary"`	Color role or hex color for the last bars

The widget height fills the available bar space automatically.

[widget.audio-vis]
type       = "audio_visualizer"
width      = 64
bands      = 20
show_when_idle = true
low_color  = "primary"
high_color = "secondary"

`media`

Shows the current media artwork and track title from MPRIS.

Setting	Type	Default	Description
`min_length`	number	`80`	Minimum widget length in pixels
`max_length`	number	`220`	Maximum widget length in pixels
`art_size`	number	`16`	Artwork size in pixels before scale
`title_scroll`	string	`"none"`	Media title scrolling mode: `"none"`, `"always"`, or `"on_hover"`

[widget.media]
min_length = 80
max_length = 220
art_size   = 24
title_scroll = "on_hover"

`battery`

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

Setting	Type	Default	Description
`device`	string	`auto`	UPower device selector. `auto` monitors the system power-supply battery only; explicit selectors can target any present battery-capable UPower device.

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"

# 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 display brightness level and adjusts it via scroll wheel (±5% per step). Hides itself when no controllable display is found. Click opens the display tab in the control center.

Setting	Type	Default	Description
`show_label`	bool	`true`	Show the brightness percentage next to the glyph (horizontal and vertical bars)

[widget.brightness]
show_label = false

See [brightness] for backend configuration.

`bluetooth`

Shows the Bluetooth adapter state and connected device. Click opens the Bluetooth tab in the control center.

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. Dims and shows a wifi-off glyph when disconnected.

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
`display`	string	`"short"`	`"short"` = compact code; `"full"` = full layout name
`cycle_command`	string	`""`	Optional override command run on left click instead of compositor backend

[widget.keyboard_layout]
display = "short"   # short | full

`lock_keys`

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

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

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

`clipboard`

Shows a clipboard glyph and opens or closes the clipboard panel on click.

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

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

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

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

`tray`

System tray (StatusNotifierItem).

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

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 `start_time`/`stop_time` or location
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 toggle-nightlight
noctalia msg toggle-force-nightlight

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

`scripted`

Custom widget driven by a Luau script. See Scripted widgets for the full Lua API reference, callbacks, and examples.

Setting	Type	Default	Description
`script`	string	`""`	Path to the Luau script file (`~` is expanded)
`hot_reload`	bool	`false`	Watch the script file and reload on change (dev tool)

[widget.my_widget]
type       = "scripted"
script     = "~/.config/noctalia/scripts/my_widget.lua"
hot_reload = true