waybar-hyprland-workspaces(5)

📦

version 0.15.0 · 10 versions

0.15.0 · ubuntu resolute, ubuntu stonking (latest)
0.11.0 · opensuse-leap 16.0
0.15.0 · nixos 26.05
0.15.0 · nixpkgs unstable
0.15.0 · alpine 3.24
0.15.0 · arch rolling
0.14.0 · fedora 43
0.15.0 · fedora 44
0.15.0 · fedora 44
0.12.0 · debian trixie, ubuntu questing

💖 waybar-hyprland-workspaces(5) — the waybar hyprland workspaces module, bestie edition 💖

okay so this is the manual page for waybar-hyprland-workspaces, from the File Formats Manual, and it's literally the whole guide to making your workspaces look cute on Hyprland. grab a strawberry 🍓 and let's go.

🌸 NAME 🌸

waybar — hyprland workspaces module. that's it, that's the name, we move.

✨ DESCRIPTION ✨

The workspaces module displays the currently used workspaces in hyprland compositor. that's the whole vibe: your workspaces, on your bar, looking gorgeous. 👑

🎀 CONFIGURATION 🎀

You reach this module by addressing it as hyprland/workspaces in your config. no cap.

format
- typeof: string
- default: {id}
- The format, how information should be displayed. this is the main character of your setup fr.
format-icons
- typeof: array
- Based on the workspace ID and state, the corresponding icon gets selected. See icons. (yes, there's a whole ICONS section below, patience bestie 💅)
window-rewrite
- typeof: object
- Regex rules to map window class to an icon or preferred method of representation for a workspace's window.
  - Keys are the rules, while the values are the methods of representation. Values may use the placeholders {class} and {title} to use the window's original class and/or title respectively. Rules may specify class<...>, title<...>, or both in order to fine-tune the matching. You may assign an empty value to a rule to have it ignored from generating any representation in workspaces.
  - This setting is ignored if workspace-taskbar.enable is set to true. (so if you turned on the taskbar, this one's just sitting there like 🙈)
window-rewrite-default
- typeof: string
- default: "?"
- The default method of representation for a workspace's window. This will be used for windows whose classes do not match any of the rules in window-rewrite.
- This setting is ignored if workspace-taskbar.enable is set to true.
format-window-separator
- typeof: string
- default: " "
- The separator to be used between windows in a workspace.
- This setting is ignored if workspace-taskbar.enable is set to true.
workspace-taskbar
- typeof: object
- Contains settings for the workspace taskbar, an alternative mode for the workspaces module which displays the window icons as images instead of text. iconic, honestly. 🖼️
- enable
  - typeof: bool
  - default: false
  - Enables the workspace taskbar mode.
- update-active-window
  - typeof: bool
  - default: false
  - If true, the active/focused window will have an 'active' class.
  - Could cause higher CPU usage due to more frequent redraws. ⚠️ (your fans will be screaming, just so you know)
- reverse-direction
  - typeof: bool
  - default: false
  - If true, the taskbar windows will be added in reverse order (right to left if orientation is horizontal, bottom to top if vertical).
- active-window-position
  - typeof: "none" | "first" | "last"
  - default: "none"
  - If set to "first", the active window will be moved at the beginning of the taskbar. If set to "last", it will be moved at the end. It will only work if update-active-window is set to true. (no update-active-window, no reordering, that's the deal 🤝)
- format
  - typeof: string
  - default: {icon}
  - Format to use for each window in the workspace taskbar.
  - Available placeholders are {icon} and {title}.
- icon-size
  - typeof: int
  - default: 16
  - Size of the icons in the workspace taskbar.
- icon-theme
  - typeof: string | array
  - default: []
  - Icon theme to use for the workspace taskbar. If an array is provided, the first theme that is found for a given icon will be used. If no theme is found (or the array is empty), the default icon theme is used.
- orientation
  - typeof: "horizontal" | "vertical"
  - default: horizontal
  - Direction in which the workspace taskbar is displayed.
- ignore-list
  - typeof: array
  - default: []
  - Regex patterns to match against window class or window title. If a window's class OR title matches any of the patterns, it will not be shown. (bye bye 👋 not on my bar)
- on-click-window
  - typeof: string
  - default: ""
  - Command to run when a window is clicked. Available placeholders are:
    - {address} Hyprland address of the clicked window.
    - {button} Pressed button number, see https://api.gtkd.org/gdk.c.types.GdkEventButton.button.html.
  - See https://github.com/Alexays/Waybar/wiki/Module:-Hyprland#workspace-taskbars-example for a full example. 🫶
show-special
- typeof: bool
- default: false
- If set to true, special workspaces will be shown.
special-visible-only
- typeof: bool
- default: false
- If this and show-special are to true, special workspaces will be shown only if visible.
persistent-only
- typeof: bool
- default: false
- If set to true, only persistent workspaces will be shown on bar.
all-outputs
- typeof: bool
- default: false
- If set to false workspaces group will be shown only in assigned output. Otherwise, all workspace groups are shown.
active-only
- typeof: bool
- default: false
- If set to true, only the active workspace will be shown. minimalism era ✨
move-to-monitor
- typeof: bool
- default: false
- If set to true, open the workspace on the current monitor when clicking on a workspace button.
  - Otherwise, the workspace will open on the monitor where it was previously assigned. Analog to using focusworkspaceoncurrentmonitor dispatcher instead of workspace in Hyprland.
ignore-workspaces
- typeof: array
- default: []
- Regexes to match against workspaces names. If there's a match, the workspace will not be shown. This takes precedence over show-special, all-outputs, and active-only. (it wins, periodt 💅)
sort-by
- typeof: string
- default: "default"
- If set to number, workspaces will sort by number.
  - If set to name, workspaces will sort by name. If set to id, workspaces will sort by id. If set to special-centered, workspaces will sort by default with special workspaces in the center. If none of those, workspaces will sort with default behavior.
expand
- typeof: bool
- default: false
- Enables this module to consume all left over space dynamically. greedy little module, we love that for it 🌈

🦋 FORMAT REPLACEMENTS 🦋

{id}: id of workspace assigned by compositor
{name}: workspace name assigned by compositor
{icon}: Icon, as defined in format-icons.

⭐ ICONS ⭐

Additional to workspace name matching, the following format-icons can be set. so like, on top of matching workspace names, you also get these states:

default: Will be shown, when no string match is found and none of the below conditions have defined icons.
active: Will be shown, when workspace is active
special: Will be shown on non-active special workspaces
empty: Will be shown on non-active, non-special empty persistent workspaces
visible: Will be shown on workspaces that are visible but not active. For example: this is useful if you want your visible workspaces on other monitors to have the same look as active.
persistent: Will be shown on non-empty persistent workspaces

💜 EXAMPLES 💜

okay these are the good part, look at them closely bestie 👀

"hyprland/workspaces": {
     "format": "{name}: {icon}",
     "format-icons": {
          "1": "",
          "2": "",
          "3": "",
          "4": "",
          "5": "",
          "active": "",
          "default": ""
     },
     "persistent-workspaces": {
          "*": 5, // 5 workspaces by default on every monitor
          "HDMI-A-1": 3 // but only three on HDMI-A-1
     }
}

"hyprland/workspaces": {
     "format": "{name}: {icon}",
     "format-icons": {
          "1": "",
          "2": "",
          "3": "",
          "4": "",
          "5": "",
          "active": "",
          "default": ""
     },
     "persistent-workspaces": {
          "*": [ 2,3,4,5 ], // 2-5 on every monitor
          "HDMI-A-1": [ 1 ] // but only workspace 1 on HDMI-A-1
     }
}

"hyprland/workspaces": {
     "format": "{name}n{windows}",
     "format-window-separator": "n",
     "window-rewrite-default": "",
     "window-rewrite": {
          "title<.*youtube.*>": "", // Windows whose titles contain "youtube"
          "class<firefox>": "", // Windows whose classes are "firefox"
          "class<firefox> title<.*github.*>": "", // Windows whose class is "firefox" and title contains "github". Note that "class" always comes first.
          "foot": "", // Windows that contain "foot" in either class or title. For optimization reasons, it will only match against a title if at least one other window explicitly matches against a title.
          "code": "󰨞",
          "title<.* - (.*) - VSCodium>": "codium $1"  // captures part of the window title and formats it into output
     }
}

"hyprland/workspaces": {
     // Formatting omitted for brevity
     "ignore-workspaces": [
          "(special:)?chrome-sharing-indicator"
     ]
}

🌈 Style 🌈

these are the CSS selectors you can style, go off 💅

#workspaces
#workspaces button
#workspaces button.active
#workspaces button.empty
#workspaces button.visible
#workspaces button.persistent
#workspaces button.special
#workspaces button.urgent
#workspaces button.hosting-monitor (gets applied if workspace-monitor == waybar-monitor)
#workspaces .workspace-label
#workspaces .taskbar-window (each window in the taskbar, only if 'workspace-taskbar.enable' is true)
#workspaces .taskbar-window.active (applied to the focused window, only if 'workspace-taskbar.update-active-window' is true)

aaaand that's the whole page bestie 🫶 this came from the waybar-hyprland-workspaces(5) page, dated 2026-02-08, and it's part of the waybar docs. now go make your bar gorgeous, i'm literally obsessed with you 💖✨🎀

📦 where this page comes from

ubuntu resolute: waybar 0.15.0-1 · MIT
ubuntu stonking: waybar 0.15.0-1 · MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms