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.
Panel labels
Section titled “Panel labels”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 textlabel_format = "🍅" # a fixed glyph onlylabel_format = "Settings" # text only, no glyphlabel_format = "" # nothing at allThis 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.
System Information Widgets
Section titled “System Information Widgets”Displays CPU usage with multiple display modes.
[widgets.cpu]label_format = ""tooltip = trueround = truetemperature_unit = "celsius"sensor = "acpitz"mode = "graph" # "label" | "graph" | "circular"graph_length = 4mode: Display style —labelshows percentage text,graphshows a sparkline,circularshows 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.
Memory
Section titled “Memory”Displays memory usage with multiple display modes.
[widgets.memory]label_format = ""tooltip = truemode = "label" # "label" | "graph" | "circular"graph_length = 4unit = "gb" # Display unit for memory valuesDisplays GPU usage (supports AMD via amdgpu and NVIDIA via nvidia-smi).
[widgets.gpu]label_format = ""tooltip = truemode = "circular" # "label" | "graph" | "circular"graph_length = 4Storage
Section titled “Storage”Displays disk usage for a given path.
[widgets.storage]path = "/"label_format = ""mode = "label" # "label" | "graph" | "circular"tooltip = truegraph_length = 4unit = "gb"Network Usage
Section titled “Network Usage”Monitors real-time network upload/download speeds.
[widgets.network_usage]tooltip = truelabel_format = "{upload} {download} "upload_threshold = 1024download_threshold = 1024kb_digits = 0mb_digits = 2interval = 2000 # Polling interval in millisecondsVariables available in label_format: {upload}, {download}.
Updates
Section titled “Updates”Checks for system package updates (Arch Linux, Flatpak, Snap, Homebrew).
[widgets.updates]label_format = "{total}"pad_zero = trueavailable_icon = ""no_updates_icon = ""os = "arch"hover_reveal = falsereveal_duration = 500interval = 3600 # Refresh interval in secondstooltip = trueterminal = "kitty"auto_hide = falseflatpak = truesnap = falsebrew = falselabel_format: Variables available:{total}(the update count).pad_zero: Zero-pads{total}to two digits (05); zero itself stays0.interval: Polling interval in seconds (default: 3600 = 1 hour).os: Distribution for native package checking (supportsarch,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).
Hardware & Power Widgets
Section titled “Hardware & Power Widgets”Battery
Section titled “Battery”Shows battery level with notifications.
[widgets.battery]full_battery_level = 100hide_percent_when_full = truehide_when_missing = truetooltip = truelabel_format = "{percent}"
[widgets.battery.notifications]
[widgets.battery.notifications.low_battery]enabled = falsethreshold = 10message = "" # {percent} placeholder supported
[widgets.battery.notifications.full_battery]enabled = falsemessage = ""
[widgets.battery.notifications.charging]enabled = falsemessage = ""
[widgets.battery.notifications.unplugged]enabled = falsemessage = ""Variables available in label_format: {percent}, {time_remaining}, {capacity} (battery health), {temperature}, {state} (full / charging / discharging / unknown). The level glyph leads the label.
Notification options
Section titled “Notification options”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 belowthresholdwhile 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).
Volume
Section titled “Volume”Controls system audio output volume.
[widgets.volume]tooltip = truestep_size = 5icon_muted = ""level_icons = ["", "", "", ""]Click to toggle mute, scroll to adjust volume. level_icons maps low to maximum output volume.
Brightness
Section titled “Brightness”Controls screen and keyboard brightness.
[widgets.brightness]tooltip = truestep_size = 5level_icons = ["", "", "", ""]Requires brightnessctl. Click to toggle, scroll to adjust. level_icons maps low to maximum brightness.
Bluetooth
Section titled “Bluetooth”Manages Bluetooth connections and visibility.
[widgets.bluetooth]label_format = ""tooltip = trueenabled_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.
Microphone
Section titled “Microphone”Shows microphone status and muting.
[widgets.microphone]tooltip = truelabel_format = ""icon_active = ""icon_muted = ""Supports the {state} field ("muted" / "on"); icon_active and icon_muted set the glyph.
Click to toggle microphone mute.
Power Button
Section titled “Power Button”System power menu with shutdown, reboot, suspend, hibernate, lock, and logout.
[widgets.power]tooltip = trueitems_per_row = 3icon_size = 100label_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.
Hypridle
Section titled “Hypridle”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 = trueHyprsunset
Section titled “Hyprsunset”Toggle blue-light filter (night mode) via Hyprsunset.
[widgets.hyprsunset]temperature = "2800k"gamma = 100enabled_icon = ""label_format = "{state}"disabled_icon = ""tooltip = trueHyprpicker
Section titled “Hyprpicker”Color picker that captures a color from the screen.
[widgets.hyprpicker]tooltip = truequiet = falselabel_format = ""The selected color is copied to clipboard. In quiet mode, no notification is shown.
Desktop & Workspace Widgets
Section titled “Desktop & Workspace Widgets”Workspaces
Section titled “Workspaces”Displays virtual desktops with click/scroll switching. See the full Workspaces documentation for details.
[widgets.workspaces]count = 10hide_unoccupied = trueignored = [-99]reverse_scroll = falsestyle = "numbered" # "numbered" | "pill" | "icon" | "default" | "underline" | "bubble"empty_scroll = falselabel_format = "{id}"icon_map = {}show_special = falseshow_urgent = falsestyle: Choose fromnumbered,pill,icon,default,underline, orbubble.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 tofalseto hide them.show_urgent: Show pulse animation and color on workspaces with urgent windows. Set totrueto enable.
Window Title
Section titled “Window Title”Shows the title of the currently focused window.
[widgets.window_title]icon = truetruncation = truetruncation_size = 50tooltip = truemappings = truetitle_map = []fallback = "class" # "class" | "title"fallback_icon = "" # Glyph for the fallback title; "" drops ittitle_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 notitle_maprule matches. Defaults to a window glyph; set it to""to show the bare title. Note thaticon = falseonly drops the glyph fromtitle_mapmatches, not from the fallback.
Window Count
Section titled “Window Count”Shows the number of windows in the current workspace.
[widgets.window_count]label_format = " [{count}]"hide_when_zero = truetooltip = trueVariables available in label_format: {count}.
Overview Button
Section titled “Overview Button”Button that opens the window overview/exposé.
[widgets.overview_button]label_format = ""tooltip = trueTaskbar
Section titled “Taskbar”Shows running applications as clickable icons similar to a traditional taskbar.
[widgets.taskbar]icon_size = 22ignored = []tooltip = trueshow_current_workspace_only = falseDate, Time & Calendar
Section titled “Date, Time & Calendar”Date & Time Menu
Section titled “Date & Time Menu”Shows the current date/time with a calendar popover and event notifications.
[widgets.date_time]date_format = " %a %b %d,"calendar = trueclock_format = "12h" # "12h" | "24h"hover_reveal = falsereveal_duration = 500
[widgets.date_time.notification]enabled = truecount = truehide_count_on_zero = trueWorld Clock
Section titled “World Clock”Shows time in multiple timezones.
[widgets.world_clock]use_24hr = truelabel_format = ""timezones = ["America/New_York", "Asia/Tokyo"]Media & Audio Widgets
Section titled “Media & Audio Widgets”MPRIS Media Controls
Section titled “MPRIS Media Controls”Displays currently playing media with playback controls.
[widgets.mpris]truncation_size = 20tooltip = truelabel_format = "{title} - {artist}"hide_when_no_player = trueignore = []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.
Cava Audio Visualizer
Section titled “Cava Audio Visualizer”Real-time audio visualization powered by Cava.
[widgets.cava]bars = 10color = "#89b4fa"Requires Cava to be installed and configured.
System Utilities
Section titled “System Utilities”Screenshot
Section titled “Screenshot”Capture screenshots with annotation support.
[widgets.screenshot]path = "Pictures/Screenshots"label_format = ""tooltip = trueannotation = truedelayed = falsedelayed_timeout = 5000capture_sound = falseUses grimblast for captures and satty for annotations.
Screen Recording
Section titled “Screen Recording”Start/stop screen recording with optional audio.
[widgets.recorder]path = "Videos/Screencasting"tooltip = trueaudio = truedelayed = falsedelayed_timeout = 5000Uses wf-recorder for recording.
OCR (Optical Character Recognition)
Section titled “OCR (Optical Character Recognition)”Extract text from a screen region using Tesseract.
[widgets.ocr]tooltip = truelabel_format = ""quiet = falseSupports the {lang} field, which renders the active tesseract language (e.g. eng).
Requires tesseract, slurp, and imagemagick.
Clipboard Manager
Section titled “Clipboard Manager”Clipboard history manager with image support.
[widgets.clipboard]label_format = ""tooltip = trueitem_tooltip = falseshow_images = trueenable_pinning = trueUses cliphist for clipboard history.
USB Manager
Section titled “USB Manager”Manage USB drive mounting and ejection.
[widgets.usb_manager]label_format = ""tooltip = trueSupports 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.
Input & Language Widgets
Section titled “Input & Language Widgets”Keyboard Layout
Section titled “Keyboard Layout”Displays the current keyboard layout.
[widgets.keyboard]tooltip = truelabel_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.
Language
Section titled “Language”Shows the current input language.
[widgets.language]tooltip = truetruncation_size = 2label_format = ""Submap
Section titled “Submap”Displays the active Hyprland keybind submap.
[widgets.submap]tooltip = truelabel_format = " {submap}"hide_on_default = falseHides automatically when the active submap is the default.
UI & Application Widgets
Section titled “UI & Application Widgets”Launcher Button
Section titled “Launcher Button”Opens the application launcher popup.
[widgets.launcher_button]label_format = ""tooltip = trueQuick Settings
Section titled “Quick Settings”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 = falsetoggles = ["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 = trueignore = []truncation_size = 30show_album = trueshow_artist = trueshow_player_icon = trueshow_time = trueshow_time_tooltip = true# Hide the media section when no player is playing or pausedhide_when_stopped = true
[widgets.quick_settings.shortcuts]enabled = true
[[widgets.quick_settings.shortcuts.items]]icon = ""label = "Terminal"command = "kitty"tooltip = "Open terminal"icon_size = 18System Tray
Section titled “System Tray”System tray for background applications (NetworkManager, Bluetooth, etc.).
[widgets.system_tray]icon_size = 16ignored = []hidden = []overrides = {} # glob pattern -> icon name or file path, first match winshide_when_empty = falseWallpaper Button
Section titled “Wallpaper Button”Opens the wallpaper selection popup.
[widgets.wallpaper]label_format = ""tooltip = trueSettings Button
Section titled “Settings Button”Opens the in-app settings GUI.
[widgets.settings]label_format = ""tooltip = trueTheme Switcher
Section titled “Theme Switcher”Quickly switch between installed themes.
[widgets.theme_switcher]label_format = ""notify = false # Show notification on theme changeCheatsheet
Section titled “Cheatsheet”Displays a searchable keybind cheatsheet for Hyprland.
[widgets.cheatsheet]label_format = "" # the fixed glyph; "" for no label at alltooltip = truetitle = "Hyprland Cheatsheet"columns = 3groups_per_page = 6max_entries_per_group = 8Emoji Picker
Section titled “Emoji Picker”Search and insert emoji characters.
[widgets.emoji_picker]label_format = ""tooltip = trueper_row = 9per_column = 4Kanban Board
Section titled “Kanban Board”A simple Kanban task management board.
[widgets.kanban]label_format = ""tooltip = truePomodoro Timer
Section titled “Pomodoro Timer”A Pomodoro productivity timer.
[widgets.pomodoro]label_format = "🍅"tooltip = trueGitHub Tray
Section titled “GitHub Tray”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:
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.comhostname = ""avatar_size = 44default_tab = "inbox" # "inbox" | "repos"max_repos = 10sort_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 = 3600notification_interval = 60 # seconds between unread refreshesworkflow_runs_max = 10show_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 = truementions = trueassignments = truepr_comments = trueissue_comments = true
[widgets.github_tray.alerts]enabled = truenew_stars = truenew_forks = truenew_issues = truenew_followers = truenew_notifications = trueworkflow_started = trueworkflow_success = trueworkflow_failure = trueworkflow_cancelled = trueCloudflare WARP
Section titled “Cloudflare WARP”Manage Cloudflare WARP VPN connection — connect, disconnect, and view status.
[widgets.cloudflare_warp]label_format = ""tooltip = trueconnected_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-clifrom Cloudflare WARP Client for Linux. - The service polls
warp-cli statusevery 5 seconds to detect state changes.
DNS Switcher
Section titled “DNS Switcher”Quickly switch between popular DNS providers directly from the bar.
[widgets.dns_switcher]label_format = ""tooltip = trueSupports 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 |
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
nmclievery 3 seconds to detect the current DNS server.
IP Monitor
Section titled “IP Monitor”Displays the current IP address.
[widgets.ip_monitor]label_format = ""tooltip = trueStopwatch
Section titled “Stopwatch”A simple stopwatch/timer.
[widgets.stopwatch]stopped_icon = ""running_icon = ""Click Counter
Section titled “Click Counter”A counter that increments on each click.
[widgets.click_counter]count = 0Breathe
Section titled “Breathe”A breathing exercise guide widget.
[widgets.breathe]label_format = ""tooltip = trueWeather
Section titled “Weather”Displays current weather conditions for a location.
[widgets.weather]location = "kathmandu"label_format = "{temperature} {condition}"tooltip = trueexpanded = truetemperature_unit = "celsius" # "celsius" | "fahrenheit"wind_speed_unit = "kmh" # "kmh" | "mph" | "ms" | "beaufort"time_format = "12h" # "12h" | "24h"interval = 86400hover_reveal = truereveal_duration = 500provider = "open-meteo" # "open-meteo" | "wttr"Variables available in label_format: {location}, {temperature}, {condition}, {humidity}, {wind_speed}, {sunrise}, {sunset}.
Layout & Grouping Widgets
Section titled “Layout & Grouping Widgets”Divider
Section titled “Divider”A visual separator between bar sections.
[widgets.divider]size = 2For advanced configuration, see Advanced Configuration for configuration and usage.