.\" 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\-sway\-workspaces" "5" "2026\-08\-31"
.PP
.SH NAME
.PP
waybar \- sway workspaces module
.PP
.SH DESCRIPTION
.PP
The \fBworkspaces\fR module displays the currently used workspaces in Sway.\&
.PP
.SH CONFIGURATION
.PP
Addressed by \fBsway/workspaces\fR
.PP
\fBall\-outputs\fR: 
.br
typeof: bool 
.br
default: false 
.br
If set to false, workspaces will only be shown on the output they are on.\& If set to true all workspaces will be shown on every output.\&
.PP
\fBformat\fR: 
.br
typeof: string 
.br
default: {value} 
.br
The format, how information should be displayed.\&
.PP
\fBformat\-icons\fR: 
.br
typeof: array 
.br
Based on the workspace name and state, the corresponding icon gets selected.\& See \fBicons\fR.\&
.PP
\fBdisable\-scroll\fR: 
.br
typeof: bool 
.br
default: false 
.br
If set to false, you can scroll to cycle through workspaces.\& If set to true this behaviour is disabled.\&
.PP
\fBreverse\-scroll\fR: 
.br
typeof: bool 
.br
default: false 
.br
If set to false, scrolling up will switch to the previous workspace and scrolling down will switch to the next workspace.\& If set to true, the behavior will be reversed.\&
.PP
\fBdisable\-click\fR: 
.br
typeof: bool 
.br
default: false 
.br
If set to false, you can click to change workspace.\& If set to true this behaviour is disabled.\&
.PP
\fBsmooth\-scrolling\-threshold\fR: 
.br
typeof: double 
.br
Threshold to be used when scrolling.\&
.PP
\fBdisable\-scroll\-wraparound\fR: 
.br
typeof: bool 
.br
default: false 
.br
If set to false, scrolling on the workspace indicator will wrap around to the first workspace when reading the end, and vice versa.\& If set to true this behavior is disabled.\&
.PP
\fBenable\-bar\-scroll\fR: 
.br
typeof: bool 
.br
default: false 
.br
If set to false, you can'\&t scroll to cycle throughout workspaces from the entire bar.\& If set to true this behaviour is enabled.\&
.PP
\fBdisable\-markup\fR: 
.br
typeof: bool 
.br
default: false 
.br
If set to true, button label will escape pango markup.\&
.PP
\fBcurrent\-only\fR: 
.br
typeof: bool 
.br
default: false 
.br
If set to true.\& Only focused workspaces will be shown.\&
.PP
\fBpersistent\-workspaces\fR: 
.br
typeof: json (see below) 
.br
default: empty 
.br
Lists workspaces that should always be shown, even when non\-existent
.PP
\fBon\-update\fR: 
.br
typeof: string 
.br
Command to execute when the module is updated.\&
.PP
\fBdisable\-auto\-back\-and\-forth\fR: 
.br
typeof: bool 
.br
Whether to disable \fBworkspace_auto_back_and_forth\fR when clicking on workspaces.\& If this is set to \fBtrue\fR, clicking on a workspace you are already on won'\&t do anything, even if \fBworkspace_auto_back_and_forth\fR is enabled in the Sway configuration.\&
.PP
\fBalphabetical_sort\fR: 
.br
typeof: bool 
.br
Whether to sort workspaces alphabetically.\& Please note this can make "swaymsg workspace prev/next" move to workspaces inconsistent with the ordering shown in Waybar.\&
.PP
warp\-on\-scroll: 
.br
typeof: bool 
.br
default: true 
.br
If set to false, you can scroll to cycle through workspaces without mouse warping being enabled.\& If set to true this behaviour is disabled.\&
.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.\&
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.\&
For Wayland windows `class` is matched against the `app_id`, and for X11 windows against the `class` property.\&
.PP
.RE
\fBwindow\-rewrite\-default\fR:
.RS 4
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.\&
.PP
.RE
\fBformat\-window\-separator\fR: 
.br
typeof: string 
.br
default: " " 
.br
The separator to be used between windows in a workspace.\&
.PP
\fBexpand\fR: 
.br
typeof: bool 
.br
default: false 
.br
Enables this module to consume all left over space dynamically.\&
.PP
.PP
.SH FORMAT REPLACEMENTS
.PP
\fB{value}\fR: Name of the workspace, as defined by sway.\&
.PP
\fB{name}\fR: Number stripped from workspace value.\&
.PP
\fB{icon}\fR: Icon, as defined in \fBformat\-icons\fR.\&
.PP
\fB{index}\fR: Index of the workspace.\&
.PP
\fB{output}\fR: Output where the workspace is located.\&
.PP
\fB{windows}\fR: Result from window\-rewrite
.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 matches are found.\&
.IP \(bu 4
\fBurgent\fR: Will be shown, when workspace is flagged as urgent
.IP \(bu 4
\fBfocused\fR: Will be shown, when workspace is focused
.IP \(bu 4
\fBpersistent\fR: Will be shown, when workspace is persistent.\&
.IP \(bu 4
\fBhigh\-priority\-named\fR: Icons by names will be shown always for those workspaces, independent by state.\&
.PD
.PP
.SH PERSISTENT WORKSPACES
.PP
Each entry of \fBpersistent_workspace\fR names a workspace that should always be shown.\&
Associated with that value is a list of outputs indicating \fBwhere\fR the workspace should be shown,
an empty list denoting all outputs.\&
.PP
.nf
.RS 4
"sway/workspaces": {
	"persistent\-workspaces": {
		"3": [], // Always show a workspace with name \&'3\&', on all outputs if it does not exist
		"4": ["eDP\-1"], // Always show a workspace with name \&'4\&', on output \&'eDP\-1\&' if it does not exist
		"5": ["eDP\-1", "DP\-2"] // Always show a workspace with name \&'5\&', on outputs \&'eDP\-1\&' and \&'DP\-2\&' if it does not exist
	}
}
.fi
.RE
.PP
n.\&b.\&: the list of outputs can be obtained from command line using \fBswaymsg \-t get_outputs\fR
.PP
.SH EXAMPLES
.PP
.nf
.RS 4
"sway/workspaces": {
	"disable\-scroll": true,
	"all\-outputs": true,
	"format": "{name}: {icon}",
	"format\-icons": {
		"1": "",
		"2": "",
		"3": "",
		"4": "",
		"5": "",
		"high\-priority\-named": [ "1", "2" ],
		"urgent": "",
		"focused": "",
		"default": ""
	}
}
.fi
.RE
.PP
.nf
.RS 4
"sway/workspaces": {
  "format": "<span size=\&'larger\&'>{name}</span> {windows}",
  "format\-window\-separator": " | ",
  "window\-rewrite\-default": "{name}",
  "window\-rewrite": {
    "class<firefox>": "",
    "class<kitty>": "k",
	"title<\&.* \- (\&.*) \- VSCodium>": "codium $1"  // captures part of the window title and formats it into output
  }
}
.fi
.RE
.PP
.SH Style
.PP
.PD 0
.IP \(bu 4
\fB#workspaces button\fR
.IP \(bu 4
\fB#workspaces button.\&visible\fR
.IP \(bu 4
\fB#workspaces button.\&focused\fR
.IP \(bu 4
\fB#workspaces button.\&urgent\fR
.IP \(bu 4
\fB#workspaces button.\&persistent\fR
.IP \(bu 4
\fB#workspaces button.\&empty\fR
.IP \(bu 4
\fB#workspaces button.\&current_output\fR
.IP \(bu 4
\fB#workspaces button#sway\-workspace\-${name}\fR