Skip to content

Widgets Reference

This page documents every widget available in Tsumiki, its configuration options, defaults, and behavior.

Widgets are configured under [widgets.<name>] in config.toml and placed in the bar via layout sections.

label_format is the whole panel label. The widget renders one label and there is no separate icon key: the glyph is written directly into label_format as a literal character. Any literal text in the string is kept, so the text next to a glyph is part of the format rather than a separate toggle.

A widget whose glyph changes with state — Bluetooth, microphone mute, the update count, the WARP connection — supplies that glyph itself and leads the label with it, so its label_format holds only the text you want beside it.

label_format = "󰌌 {layout}" # a fixed glyph plus literal text
label_format = "🍅" # a fixed glyph only
label_format = "Settings" # text only, no glyph
label_format = "" # nothing at all

This replaced the old per-widget show_icon boolean and the label / label_text keys, none of which are read any more — a config that still sets show_icon logs a warning at startup and falls back to the default.

No widget substitutes an {icon} field any more: the glyph is a literal character in label_format, and a widget whose glyph changes with state supplies it ahead of the text. Widgets that print live values declare fields for them: mpris ({title}, {artist}, {album}, {name}), weather ({location}, {temperature}, {condition}, {humidity}, {wind_speed}, {sunrise}, {sunset}), network_usage ({upload}, {download}), window_count ({count}), workspaces ({id}), updates ({total}), hypridle, hyprsunset, bluetooth, microphone and cloudflare_warp ({state}), dns_switcher ({current_dns}), ocr ({lang}), keyboard ({layout}), language ({language}), submap ({submap}), theme_switcher ({theme}), usb_manager ({count}), github_tray ({unread}) and battery ({percent}, {time_remaining}, {capacity}, {temperature}, {state}).

Indexed entries follow the same rule: a [[collapsible_groups]] toggle button labels itself with label_format, with its glyph written straight into the string.


Displays CPU usage with multiple display modes.

[widgets.cpu]
label_format = ""
tooltip = true
round = true
temperature_unit = "celsius"
sensor = "acpitz"
mode = "graph" # "label" | "graph" | "circular"
graph_length = 4
  • mode: Display style — label shows percentage text, graph shows a sparkline, circular shows a circular progress ring.
  • graph_length: Number of data points for the sparkline graph.
  • sensor: Thermal zone sensor path (e.g. acpitz, k10temp). Leave empty for auto-detect.

Displays memory usage with multiple display modes.

[widgets.memory]
label_format = ""
tooltip = true
mode = "label" # "label" | "graph" | "circular"
graph_length = 4
unit = "gb" # Display unit for memory values

Displays GPU usage (supports AMD via amdgpu and NVIDIA via nvidia-smi).

[widgets.gpu]
label_format = ""
tooltip = true
mode = "circular" # "label" | "graph" | "circular"
graph_length = 4

Displays disk usage for a given path.

[widgets.storage]
path = "/"
label_format = "󰋊"
mode = "label" # "label" | "graph" | "circular"
tooltip = true
graph_length = 4
unit = "gb"

Monitors real-time network upload/download speeds.

[widgets.network_usage]
tooltip = true
label_format = "{upload}  {download} "
upload_threshold = 1024
download_threshold = 1024
kb_digits = 0
mb_digits = 2
interval = 2000 # Polling interval in milliseconds

Variables available in label_format: {upload}, {download}.

Checks for system package updates (Arch Linux, Flatpak, Snap, Homebrew).

[widgets.updates]
label_format = "{total}"
pad_zero = true
available_icon = "󰏗"
no_updates_icon = "󰏖"
os = "arch"
hover_reveal = false
reveal_duration = 500
interval = 3600 # Refresh interval in seconds
tooltip = true
terminal = "kitty"
auto_hide = false
flatpak = true
snap = false
brew = false
  • label_format: Variables available: {total} (the update count).
  • pad_zero: Zero-pads {total} to two digits (05); zero itself stays 0.
  • interval: Polling interval in seconds (default: 3600 = 1 hour).
  • os: Distribution for native package checking (supports arch, fedora, ubuntu).
  • flatpak/snap/brew: Enable checking for these package formats.
  • hover_reveal: Hide the count behind a revealer that slides open on hover (default: false).
  • reveal_duration: Hover-reveal transition in milliseconds (default: 500).

Shows battery level with notifications.

[widgets.battery]
full_battery_level = 100
hide_percent_when_full = true
hide_when_missing = true
tooltip = true
label_format = "{percent}"
[widgets.battery.notifications]
[widgets.battery.notifications.low_battery]
enabled = false
threshold = 10
message = "" # {percent} placeholder supported
[widgets.battery.notifications.full_battery]
enabled = false
message = ""
[widgets.battery.notifications.charging]
enabled = false
message = ""
[widgets.battery.notifications.unplugged]
enabled = false
message = ""

Variables available in label_format: {percent}, {time_remaining}, {capacity} (battery health), {temperature}, {state} (full / charging / discharging / unknown). The level glyph leads the label.

Each notification type is a separate table with the following fields:

Field Types Description
enabled all Whether to show this notification.
threshold low_battery only Battery percentage that triggers the low-battery alert (default: 10).
message all Custom body text. Supports {percent} placeholder. Falls back to the default i18n string when empty.

Notification types:

  • low_battery – Fires when the battery drops to or below threshold while discharging.
  • full_battery – Fires when the charger is unplugged and the battery is at 100%.
  • charging – Fires when the charger is plugged in.
  • unplugged – Fires when the charger is disconnected (and the battery is not full).

Controls system audio output volume.

[widgets.volume]
tooltip = true
step_size = 5
icon_muted = "󰝟"
level_icons = ["󰕿", "󰖀", "󰕾", "󱄠"]

Click to toggle mute, scroll to adjust volume. level_icons maps low to maximum output volume.

Controls screen and keyboard brightness.

[widgets.brightness]
tooltip = true
step_size = 5
level_icons = ["󰃞", "󰃝", "󰃟", "󰃠"]

Requires brightnessctl. Click to toggle, scroll to adjust. level_icons maps low to maximum brightness.

Manages Bluetooth connections and visibility.

[widgets.bluetooth]
label_format = ""
tooltip = true
enabled_icon = "󰂱"
disabled_icon = "󰂲"

Supports the {state} field ("on" / "off"); enabled_icon and disabled_icon set the glyph.

Opens a popover to manage paired devices and toggle Bluetooth.

Shows microphone status and muting.

[widgets.microphone]
tooltip = true
label_format = ""
icon_active = ""
icon_muted = ""

Supports the {state} field ("muted" / "on"); icon_active and icon_muted set the glyph.

Click to toggle microphone mute.

System power menu with shutdown, reboot, suspend, hibernate, lock, and logout.

[widgets.power]
tooltip = true
items_per_row = 3
icon_size = 100
label_format = ""
confirm = true
[widgets.power.item_shortcuts]
shutdown = "s"
reboot = "r"
hibernate = "h"
suspend = "u"
lock = "l"
logout = "o"
[widgets.power.buttons]
shutdown = "systemctl poweroff"
reboot = "systemctl reboot"
hibernate = "systemctl hibernate"
suspend = "systemctl suspend"
lock = "loginctl lock-session"
logout = "loginctl terminate-user $USER"
  • confirm: Shows a confirmation dialog before executing power actions.
  • item_shortcuts: Keyboard shortcuts for power menu items.

Hold a logind idle inhibitor so the screen stays awake; hypridle honours it. The hypridle daemon must already be running. The same toggle is available in quick settings.

[widgets.hypridle]
enabled_icon = ""
label_format = "{state}"
disabled_icon = ""
tooltip = true

Toggle blue-light filter (night mode) via Hyprsunset.

[widgets.hyprsunset]
temperature = "2800k"
gamma = 100
enabled_icon = "󱩌"
label_format = "{state}"
disabled_icon = "󰛨"
tooltip = true

Color picker that captures a color from the screen.

[widgets.hyprpicker]
tooltip = true
quiet = false
label_format = ""

The selected color is copied to clipboard. In quiet mode, no notification is shown.


Displays virtual desktops with click/scroll switching. See the full Workspaces documentation for details.

[widgets.workspaces]
count = 10
hide_unoccupied = true
ignored = [-99]
reverse_scroll = false
style = "numbered" # "numbered" | "pill" | "icon" | "default" | "underline" | "bubble"
empty_scroll = false
label_format = "{id}"
icon_map = {}
show_special = false
show_urgent = false
  • style: Choose from numbered, pill, icon, default, underline, or bubble.
  • icon_map: Map workspace IDs to custom icons: { "1": "", "2": "" }.
  • label_format: Format string with {id} variable.
  • show_special: Show special workspaces (negative IDs). Set to false to hide them.
  • show_urgent: Show pulse animation and color on workspaces with urgent windows. Set to true to enable.

Shows the title of the currently focused window.

[widgets.window_title]
icon = true
truncation = true
truncation_size = 50
tooltip = true
mappings = true
title_map = []
fallback = "class" # "class" | "title"
fallback_icon = "󰣆" # Glyph for the fallback title; "" drops it
  • title_map: List of mapping rules to rename window titles.
  • fallback: What to show when no title is available.
  • fallback_icon: Glyph prefixed to the fallback title, used when no title_map rule matches. Defaults to a window glyph; set it to "" to show the bare title. Note that icon = false only drops the glyph from title_map matches, not from the fallback.

Shows the number of windows in the current workspace.

[widgets.window_count]
label_format = " [{count}]"
hide_when_zero = true
tooltip = true

Variables available in label_format: {count}.

Button that opens the window overview/exposé.

[widgets.overview_button]
label_format = ""
tooltip = true

Shows running applications as clickable icons similar to a traditional taskbar.

[widgets.taskbar]
icon_size = 22
ignored = []
tooltip = true
show_current_workspace_only = false

Shows the current date/time with a calendar popover and event notifications.

[widgets.date_time]
date_format = " %a %b %d,"
calendar = true
clock_format = "12h" # "12h" | "24h"
hover_reveal = false
reveal_duration = 500
[widgets.date_time.notification]
enabled = true
count = true
hide_count_on_zero = true

Shows time in multiple timezones.

[widgets.world_clock]
use_24hr = true
label_format = "󱉊"
timezones = ["America/New_York", "Asia/Tokyo"]

Displays currently playing media with playback controls.

[widgets.mpris]
truncation_size = 20
tooltip = true
label_format = "{title} - {artist}"
hide_when_no_player = true
ignore = []
player_priority = ["spotify", "firefox*"]

Variables available in label_format: {title}, {artist}, {album}, {name}.

player_priority is an ordered list of glob patterns matched against player names; the first match wins, and players matching no pattern come last.

Requires playerctl. Automatically hides when no media player is running.

Real-time audio visualization powered by Cava.

[widgets.cava]
bars = 10
color = "#89b4fa"

Requires Cava to be installed and configured.


Capture screenshots with annotation support.

[widgets.screenshot]
path = "Pictures/Screenshots"
label_format = ""
tooltip = true
annotation = true
delayed = false
delayed_timeout = 5000
capture_sound = false

Uses grimblast for captures and satty for annotations.

Start/stop screen recording with optional audio.

[widgets.recorder]
path = "Videos/Screencasting"
tooltip = true
audio = true
delayed = false
delayed_timeout = 5000

Uses wf-recorder for recording.

Extract text from a screen region using Tesseract.

[widgets.ocr]
tooltip = true
label_format = ""
quiet = false

Supports the {lang} field, which renders the active tesseract language (e.g. eng).

Requires tesseract, slurp, and imagemagick.

Clipboard history manager with image support.

[widgets.clipboard]
label_format = ""
tooltip = true
item_tooltip = false
show_images = true
enable_pinning = true

Uses cliphist for clipboard history.

Manage USB drive mounting and ejection.

[widgets.usb_manager]
label_format = ""
tooltip = true

Supports the {count} field, which renders the number of mounted USB partitions. It stays empty until the popover has been opened once, since that is when the device scan runs.


Displays the current keyboard layout.

[widgets.keyboard]
tooltip = true
label_format = "󰌌 {layout}"
language_name_map = { "English (US)" = "EN", "Czech (QWERTY)" = "Czech" }
  • language_name_map: Overrides the displayed name for a layout, keyed by the raw name Hyprland reports. Unmapped layouts keep the built-in short name.

Shows the current input language.

[widgets.language]
tooltip = true
truncation_size = 2
label_format = ""

Displays the active Hyprland keybind submap.

[widgets.submap]
tooltip = true
label_format = "󰌌 {submap}"
hide_on_default = false

Hides automatically when the active submap is the default.


Opens the application launcher popup.

[widgets.launcher_button]
label_format = "󰀻"
tooltip = true

A comprehensive quick settings panel with user info, controls, media, and shortcuts.

The toggles array selects which quick settings buttons appear. Available toggles: wifi, bluetooth, power_profiles, hyprsunset, hypridle, notification, darkmode, flightmode. They flow two per row; an empty array hides the toggle section entirely. darkmode and flightmode are opt-in and not enabled by default.

[widgets.quick_settings]
hover_reveal = false
toggles = ["wifi", "bluetooth", "power_profiles", "hyprsunset", "hypridle", "notification"]
[widgets.quick_settings.user]
avatar = "~/.face"
name = "system"
distro_icon = true
[widgets.quick_settings.controls]
sliders = ["brightness", "volume"]
[widgets.quick_settings.media]
enabled = true
ignore = []
truncation_size = 30
show_album = true
show_artist = true
show_player_icon = true
show_time = true
show_time_tooltip = true
# Hide the media section when no player is playing or paused
hide_when_stopped = true
[widgets.quick_settings.shortcuts]
enabled = true
[[widgets.quick_settings.shortcuts.items]]
icon = ""
label = "Terminal"
command = "kitty"
tooltip = "Open terminal"
icon_size = 18

System tray for background applications (NetworkManager, Bluetooth, etc.).

[widgets.system_tray]
icon_size = 16
ignored = []
hidden = []
overrides = {} # glob pattern -> icon name or file path, first match wins
hide_when_empty = false

Opens the wallpaper selection popup.

[widgets.wallpaper]
label_format = ""
tooltip = true

Opens the in-app settings GUI.

[widgets.settings]
label_format = "󰒓"
tooltip = true

Quickly switch between installed themes.

[widgets.theme_switcher]
label_format = ""
notify = false # Show notification on theme change

Displays a searchable keybind cheatsheet for Hyprland.

[widgets.cheatsheet]
label_format = "󰌌" # the fixed glyph; "" for no label at all
tooltip = true
title = "Hyprland Cheatsheet"
columns = 3
groups_per_page = 6
max_entries_per_group = 8

Search and insert emoji characters.

[widgets.emoji_picker]
label_format = ""
tooltip = true
per_row = 9
per_column = 4

A simple Kanban task management board.

[widgets.kanban]
label_format = "󱞁"
tooltip = true

A Pomodoro productivity timer.

[widgets.pomodoro]
label_format = "🍅"
tooltip = true

Account-wide GitHub tray: unread notifications, repositories, and per-repository issues, pull requests and Actions runs — plus desktop alerts for new stars, followers and workflow results.

Every API call goes through the gh CLI, so install and authenticate it first:

Terminal window
gh auth login
[widgets.github_tray]
label_format = ""
tooltip = true
# Optional login used as a fallback while the gh session user is resolved.
username = ""
# GitHub Enterprise Server host (must be added to gh), empty = github.com
hostname = ""
avatar_size = 44
default_tab = "inbox" # "inbox" | "repos"
max_repos = 10
sort_by = "updated" # "updated" | "pushed" | "created" | "stars" | "name"
sort_order = "desc"
own_repos_only = false # only show repos owned by your account (hide org/collaborator)
# Seconds profile and repository data stay cached before a refetch (0 disables).
cache_ttl = 3600
notification_interval = 60 # seconds between unread refreshes
workflow_runs_max = 10
show_notifications = true
# Editor used to open locally-mapped repositories.
local_editor = "code"
# Map owner/repository to a local folder to open it in your editor from the tray.
local_projects = { "owner/repository" = "~/code/repository" }
[widgets.github_tray.notify_reasons]
review_requests = true
mentions = true
assignments = true
pr_comments = true
issue_comments = true
[widgets.github_tray.alerts]
enabled = true
new_stars = true
new_forks = true
new_issues = true
new_followers = true
new_notifications = true
workflow_started = true
workflow_success = true
workflow_failure = true
workflow_cancelled = true

Manage Cloudflare WARP VPN connection — connect, disconnect, and view status.

[widgets.cloudflare_warp]
label_format = ""
tooltip = true
connected_icon = ""
disconnected_icon = ""

Supports the {state} field ("connected" / "disconnected"); the live WARP glyph leads the label.

  • connected_icon / disconnected_icon: Nerd Font icons shown in the bar for each state.
  • Click the widget to open a popover with a toggle button.
  • Requires warp-cli from Cloudflare WARP Client for Linux.
  • The service polls warp-cli status every 5 seconds to detect state changes.

Quickly switch between popular DNS providers directly from the bar.

[widgets.dns_switcher]
label_format = "󰚘"
tooltip = true

Supports the {current_dns} field, which renders the active provider name (or the default label when DNS is untouched). The glyph is written literally into label_format.

Click to open a popover with pre-configured providers:

Provider Primary DNS Secondary DNS
Cloudflare 1.1.1.1 1.0.0.1
Google 8.8.8.8 8.8.4.4
OpenDNS 208.67.222.222 208.67.220.220
AdGuard 94.140.14.14 94.140.15.15
Quad9 9.9.9.9 149.112.112.112

Includes a “Reset to Default (ISP)” button to restore automatic DNS.

  • Uses nmcli (NetworkManager) to manage DNS settings.
  • DNS changes require Polkit authentication (pkexec).
  • The service polls nmcli every 3 seconds to detect the current DNS server.

Displays the current IP address.

[widgets.ip_monitor]
label_format = "󰖟"
tooltip = true

A simple stopwatch/timer.

[widgets.stopwatch]
stopped_icon = "󱫞"
running_icon = "󱫠"

A counter that increments on each click.

[widgets.click_counter]
count = 0

A breathing exercise guide widget.

[widgets.breathe]
label_format = ""
tooltip = true

Displays current weather conditions for a location.

[widgets.weather]
location = "kathmandu"
label_format = "{temperature} {condition}"
tooltip = true
expanded = true
temperature_unit = "celsius" # "celsius" | "fahrenheit"
wind_speed_unit = "kmh" # "kmh" | "mph" | "ms" | "beaufort"
time_format = "12h" # "12h" | "24h"
interval = 86400
hover_reveal = true
reveal_duration = 500
provider = "open-meteo" # "open-meteo" | "wttr"

Variables available in label_format: {location}, {temperature}, {condition}, {humidity}, {wind_speed}, {sunrise}, {sunset}.


A visual separator between bar sections.

[widgets.divider]
size = 2

For advanced configuration, see Advanced Configuration for configuration and usage.