.\" Generated by scdoc 1.11.5
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "waybar\-hyprland\-workspaces" "5" "2026\-08\-31"
.PP
.SH NAME
.PP
waybar \- hyprland workspaces module
.PP
.SH DESCRIPTION
.PP
The \fBworkspaces\fR module displays the currently used workspaces in hyprland compositor.\&
.PP
.SH CONFIGURATION
.PP
Addressed by \fBhyprland/workspaces\fR
.PP
\fBformat\fR: 
.br
typeof: string 
.br
default: {id} 
.br
The format, how information should be displayed.\&
.PP
\fBformat\-icons\fR: 
.br
typeof: array 
.br
Based on the workspace ID and state, the corresponding icon gets selected.\& See \fBicons\fR.\&
.PP
\fBwindow\-rewrite\fR: 
.br
typeof: object 
.br
Regex rules to map window class to an icon or preferred method of representation for a workspace'\&s window.\&
.RS 4
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.\& 
.br
This setting is ignored if \fBworkspace\-taskbar.\&enable\fR is set to true.\&
.PP
.RE
\fBwindow\-rewrite\-default\fR: 
.br
typeof: string 
.br
default: "?\&" 
.br
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 \fBwindow\-rewrite\fR.\& 
.br
This setting is ignored if \fBworkspace\-taskbar.\&enable\fR is set to true.\&
.PP
\fBformat\-window\-separator\fR: 
.br
typeof: string 
.br
default: " " 
.br
The separator to be used between windows in a workspace.\& 
.br
This setting is ignored if \fBworkspace\-taskbar.\&enable\fR is set to true.\&
.PP
\fBworkspace\-taskbar\fR: 
.br
typeof: object 
.br
Contains settings for the workspace taskbar, an alternative mode for the workspaces module which displays the window icons as images instead of text.\&
.RS 4
.PP
.RS 4
\fBenable\fR: 
.br
typeof: bool 
.br
default: false 
.br
Enables the workspace taskbar mode.\&
.PP
\fBupdate\-active\-window\fR: 
.br
typeof: bool 
.br
default: false 
.br
If true, the active/focused window will have an '\&active'\& class.\& Could cause higher CPU usage due to more frequent redraws.\&
.PP
\fBreverse\-direction\fR: 
.br
typeof: bool 
.br
default: false 
.br
If true, the taskbar windows will be added in reverse order (right to left if orientation is horizontal, bottom to top if vertical).\&
.PP
\fBactive\-window\-position\fR: 
.br
typeof: "none" | "first" | "last" 
.br
default: "none" 
.br
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 \fBupdate\-active\-window\fR is set to true.\&
.PP
\fBformat\fR: 
.br
typeof: string 
.br
default: {icon} 
.br
Format to use for each window in the workspace taskbar.\& Available placeholders are {icon} and {title}.\&
.PP
\fBicon\-size\fR: 
.br
typeof: int 
.br
default: 16 
.br
Size of the icons in the workspace taskbar.\&
.PP
\fBicon\-theme\fR: 
.br
typeof: string | array 
.br
default: [] 
.br
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.\&
.PP
\fBorientation\fR: 
.br
typeof: "horizontal" | "vertical" 
.br
default: horizontal 
.br
Direction in which the workspace taskbar is displayed.\&
.PP
\fBignore\-list\fR: 
.br
typeof: array 
.br
default: [] 
.br
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.\&
.PP
\fBon\-click\-window\fR: 
.br
typeof: string 
.br
default: "" 
.br
Command to run when a window is clicked.\& Available placeholders are: 
.br
\- {address} Hyprland address of the clicked window.\& 
.br
\- {button} Pressed button number, see https://api.\&gtkd.\&org/gdk.\&c.\&types.\&GdkEventButton.\&button.\&html.\& 
.br
See https://github.\&com/Alexays/Waybar/wiki/Module:\-Hyprland#workspace\-taskbars\-example for a full example.\&
.PP
.RE
.RE
\fBshow\-special\fR: 
.br
typeof: bool 
.br
default: false 
.br
If set to true, special workspaces will be shown.\&
.PP
\fBspecial\-visible\-only\fR: 
.br
typeof: bool 
.br
default: false 
.br
If this and show\-special are to true, special workspaces will be shown only if visible.\&
.PP
\fBpersistent\-only\fR: 
.br
typeof: bool 
.br
default: false 
.br
If set to true, only persistent workspaces will be shown on bar.\&
.PP
\fBall\-outputs\fR: 
.br
typeof: bool 
.br
default: false 
.br
If set to false workspaces group will be shown only in assigned output.\& Otherwise, all workspace groups are shown.\&
.PP
\fBactive\-only\fR: 
.br
typeof: bool 
.br
default: false 
.br
If set to true, only the active workspace will be shown.\&
.PP
\fBmove\-to\-monitor\fR: 
.br
typeof: bool 
.br
default: false 
.br
If set to true, open the workspace on the current monitor when clicking on a workspace button.\&
.RS 4
Otherwise, the workspace will open on the monitor where it was previously assigned.\&
Analog to using `focusworkspaceoncurrentmonitor` dispatcher instead of `workspace` in Hyprland.\&
.PP
.RE
\fBignore\-workspaces\fR: 
.br
typeof: array 
.br
default: [] 
.br
Regexes to match against workspaces names.\& If there'\&s a match, the workspace will not be shown.\& This takes precedence over \fBshow\-special\fR, \fBall\-outputs\fR, and \fBactive\-only\fR.\&
.PP
\fBsort\-by\fR: 
.br
typeof: string 
.br
default: "default" 
.br
If set to number, workspaces will sort by number.\&
.RS 4
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.\&
.PP
.RE
\fBexpand\fR: 
.br
typeof: bool 
.br
default: false 
.br
Enables this module to consume all left over space dynamically.\&
.PP
.SH FORMAT REPLACEMENTS
.PP
\fB{id}\fR: id of workspace assigned by compositor
.PP
\fB{name}\fR: workspace name assigned by compositor
.PP
\fB{icon}\fR: Icon, as defined in \fBformat\-icons\fR.\&
.PP
.SH ICONS
.PP
Additional to workspace name matching, the following \fBformat\-icons\fR can be set.\&
.PP
.PD 0
.IP \(bu 4
\fBdefault\fR: Will be shown, when no string match is found and none of the below conditions have defined icons.\&
.IP \(bu 4
\fBactive\fR: Will be shown, when workspace is active
.IP \(bu 4
\fBspecial\fR: Will be shown on non\-active special workspaces
.IP \(bu 4
\fBempty\fR: Will be shown on non\-active, non\-special empty persistent workspaces
.IP \(bu 4
\fBvisible\fR: 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.\&
.IP \(bu 4
\fBpersistent\fR: Will be shown on non\-empty persistent workspaces
.PD
.PP
.SH EXAMPLES
.PP
.nf
.RS 4
"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
	}
}
.fi
.RE
.PP
.nf
.RS 4
"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
	}
}
.fi
.RE
.PP
.nf
.RS 4
"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
	}
}
.fi
.RE
.PP
.nf
.RS 4
"hyprland/workspaces": {
	// Formatting omitted for brevity
	"ignore\-workspaces": [
		"(special:)?chrome\-sharing\-indicator"
	]
}
.fi
.RE
.PP
.SH Style
.PP
.PD 0
.IP \(bu 4
\fB#workspaces\fR
.IP \(bu 4
\fB#workspaces button\fR
.IP \(bu 4
\fB#workspaces button.\&active\fR
.IP \(bu 4
\fB#workspaces button.\&empty\fR
.IP \(bu 4
\fB#workspaces button.\&visible\fR
.IP \(bu 4
\fB#workspaces button.\&persistent\fR
.IP \(bu 4
\fB#workspaces button.\&special\fR
.IP \(bu 4
\fB#workspaces button.\&urgent\fR
.IP \(bu 4
\fB#workspaces button.\&hosting\-monitor\fR (gets applied if workspace\-monitor == waybar\-monitor)
.IP \(bu 4
\fB#workspaces .\&workspace\-label\fR
.IP \(bu 4
\fB#workspaces .\&taskbar\-window\fR (each window in the taskbar, only if '\&workspace\-taskbar.\&enable'\& is true)
.IP \(bu 4
\fB#workspaces .\&taskbar\-window.\&active\fR (applied to the focused window, only if '\&workspace\-taskbar.\&update\-active\-window'\& is true)