waybar-hyprland-workspaces(5)
waybar - hyprland workspaces module
The workspaces module displays the currently used workspaces in hyprland compositor.
Addressed by hyprland/workspaces
format: ++ typeof: string ++ default: {name} ++ The format, how information should be displayed.
format-icons: ++ typeof: object ++ Based on the workspace ID and state, the corresponding icon gets selected. See icons.
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.
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.
window-rewrite-group-threshold: ++ typeof: int ++ default: 0 ++ When a workspace contains at least this many windows with the same rewrite result, they are collapsed into a single one using window-rewrite-group-format. ++ Set to 0 to disable grouping. ++ This setting is ignored if workspace-taskbar.enable is set to true.
window-rewrite-group-format: ++ typeof: string ++ default: "{icon}×{count}" ++ The format used to represent a group of collapsed windows. Available placeholders are {icon} (the icon being grouped) and {count} (how many windows share it). ++ 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.
*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.
*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.
*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.
*max-icons*: ++
typeof: int ++
default: 0 (unlimited) ++
Maximum number of icons to show per workspace. When set, duplicate icons (windows with the same class) are removed first, then the list is trimmed to this limit. Set to 0 for unlimited icons.
*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.
*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.max-windows: ++ typeof: int ++ default: 0 (unlimited) ++ Maximum number of windows to show per workspace. When set, newest windows beyond the limit are not shown. Set to 0 for unlimited windows.
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.
persistent-workspaces: ++ typeof: object ++ default: empty ++ Lists workspaces that should always be shown, even when they do not exist. Keys are workspace names and values are arrays of output names on which the workspace should be shown (an empty array means all outputs). See the examples below. ++ Note: for persistent workspaces to actually work you must also declare them in your Hyprland config, e.g. workspace = 1, monitor:eDP-1, persistent:true.
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.
hide-active: ++ typeof: bool ++ default: false ++ If set to true, the active workspace will be hidden. Unless a workspace is persistent or special.
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.
unique-icons: ++ typeof: bool ++ default: false ++ If set to true, only one instance of each window icon will be shown per workspace.
enable-bar-scroll: ++ typeof: bool ++ default: false ++ If set to false, you can't scroll to cycle throughout workspaces from the entire bar. If set to true this behaviour is enabled.
on-scroll-up: ++ typeof: string ++ Command to execute when scrolling up on the module. This replaces the default behaviour of workspace cycling.
on-scroll-down: ++ typeof: string ++ Command to execute when scrolling down on the module. This replaces the default behaviour of workspace cycling.
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.
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 numerically; workspaces that have no number are grouped after them as numbered, then named, then special. 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: grouped as numbered, then named, then special, and within a group by number where there is one and by name otherwise.
tooltip: ++ typeof: bool ++ default: true ++ Option to disable tooltip on hover.
tooltips: ++ typeof: object ++ Based on the workspace ID and state, the corresponding tooltip gets selected. Selection works the same as format-icons do. Format replacements are supported. See icons.
expand: ++ typeof: bool ++ default: false ++ Enables this module to consume all left over space dynamically.
{id}: Address of the workspace as reported by the compositor. For a numbered workspace this is its number; for named and special workspaces it is the address string (for example special:magic), where older Hyprland releases reported a negative id.
{name}: workspace name assigned by compositor
{icon}: Icon, as defined in format-icons.
{windows}: The windows in the workspace, formatted according to window-rewrite and joined with format-window-separator.
The rules in window-rewrite are regexes that may match against a window's class, title, or both. There are four categories of rule, distinguished by how they are written in the config:
[- Rule :- Category |[ something :[ Vague |[ class :[ Class-only |[ title :[ Title-only |[ class title :[ Hybrid
When the config contains only "vague" rules, they are matched against window classes only. This is both for backwards compatibility and for performance: matching against the title requires listening to window title changes via Hyprland's IPC, which is unnecessary when no title rule is in use.
When the config contains at least one "title-only" or "hybrid" rule, then all "vague" rules match against both class and title. This lets you define vague rules where it does not matter whether the class or the title matched.
Additional to workspace name matching, the following format-icons can be set.
- 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
- urgent: Will be shown on non-active urgent workspaces
"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"
]
}"hyprland/workspaces": {
"format": "{icon}",
"format-window-separator": ", ",
"tooltip": true,
"tooltips": {
"default": "{name}: {windows}",
"empty": "" // Will result in no tooltip
}
"format-icons": {
"1": "",
"2": "",
"3": "",
"4": "",
"5": "",
"active": "",
"default": ""
},
// Window rewrites omitted for brevity
}"hyprland/workspaces": {
"format": "{icon}",
"format-window-separator": ", ",
"tooltip": true,
"tooltips": {
"1": "This is the first workspace",
"2": "This is the second",
"2": "And this is the third"
}
"format-icons": {
"1": "",
"2": "",
"3": "",
"4": "",
"5": "",
"active": "",
"default": ""
},
// Window rewrites omitted for brevity
}- #workspaces
- #workspaces button
- #workspaces button.active
- #workspaces button.empty
- #workspaces button.visible
- #workspaces button.persistent
- #workspaces button.special
- #workspaces button.urgent
- #workspaces button.workspace-hover (applied while the pointer is over the button)
- #workspaces button. (per-workspace class derived from the workspace name, sanitized to a valid CSS class name, e.g. a workspace named "1" yields '.ws-1'; special workspaces also get the raw name class)
- #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)