waybar-niri-workspaces(5)

# NAME

waybar - niri workspaces module

# DESCRIPTION

The *workspaces* module displays the currently used workspaces in niri.

# CONFIGURATION

Addressed by *niri/workspaces*

*all-outputs*: ++
	typeof: bool ++
	default: false ++
	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.

*sort-by-name*: ++
	typeof: bool ++
	default: false ++
	Sort workspaces by name (numeric sort when all names are numbers). Unnamed workspaces fall back to their index on the output.

*sort-by-coordinates*: ++
	typeof: bool ++
	default: false ++
	Sort workspaces by output and index. If both *sort-by-name* and *sort-by-coordinates* are true, sorting by name is applied.

*sort-by-id*: ++
	typeof: bool ++
	default: false ++
	Sort workspaces by id, taking precedence over other sort options.

*sort-by-number*: ++
	typeof: bool ++
	default: false ++
	Deprecated alias for *sort-by-id*; prefer *sort-by-id* instead.

If none of the sorting options are enabled, workspaces keep their output/index order.

*format*: ++
	typeof: string ++
	default: {value} ++
	The format, how information should be displayed.

*format-icons*: ++
	typeof: array ++
	Based on the workspace name, index and state, the corresponding icon gets selected. See *icons*.

*disable-click*: ++
	typeof: bool ++
	default: false ++
	If set to false, you can click to change workspace. If set to true this behaviour is disabled.

*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.

*disable-markup*: ++
	typeof: bool ++
	default: false ++
	If set to true, button label will escape pango markup.

*current-only*: ++
	typeof: bool ++
	default: false ++
	If set to true, only the active or focused workspace will be shown.

*display-condition*: ++
	typeof: string ++
	oneof: "show-all", "keep-named", "only-populated" ++
	default: "show-all" ++
	Specifies the conditions for showing workspace widgets. ++
	++
	*show-all*: displays widgets for all workspaces. ++
	*keep-named*: always displays named workspaces, irrespective of whether they contain windows or not. ++
	*only-populated*: only displays widgets for workspaces that have windows.

*hide-empty*: ++
	typeof: bool ++
	default: false ++
	If set to true, empty workspaces will not be shown.

*on-update*: ++
	typeof: string ++
	Command to execute when the module is updated.

*expand*: ++
	typeof: bool ++
	default: false ++
	Enables this module to consume all left over space dynamically.
	
*workspace-taskbar*: ++
	typeof: object ++
	Contains settings for the workspace taskbar, which displays app icons within each workspace.

	*enable*: ++
		typeof: bool ++
		default: false ++
		Enables the workspace taskbar mode.

	*icon-size*: ++
		typeof: int ++
		default: 18 ++
		Size of the icons in the workspace taskbar.

*ignore-workspaces*: ++
	typeof: array ++
	default: [] ++
	Regexes to match against workspaces names and index's. If there's a match, the workspace will not be shown.

*format-window-separator*: ++
	typeof: string ++
	default: " " ++
	Separator used between window representations generated by *window-rewrite*.

*window-rewrite*: ++
	typeof: object ++
	default: {} ++
	Rules to map window app_id and/or title to a specific string representation (e.g., an icon). Keys are regular expressions matching `app_id<regex>` and/or `title<regex>`. Values are the replacement strings, which can contain `{app_id}` and `{title}` placeholders.

*window-rewrite-default*: ++
	typeof: string ++
	default: "?" ++
	The default representation for windows that don't match any rule in *window-rewrite*.

# FORMAT REPLACEMENTS

*{value}*: Name of the workspace, or index for unnamed workspaces,
as defined by niri.

*{name}*: Name of the workspace for named workspaces.

*{icon}*: Icon, as defined in *format-icons*.

*{index}*: Index of the workspace on its output.

*{output}*: Output where the workspace is located.

*{total}*: The total number of workspaces.

*{windows}*: Concatenated representation of windows in the workspace, using *window-rewrite* rules and *format-window-separator*.

# ICONS

Additional to workspace name matching, the following *format-icons* can be set.

- *default*: Will be shown, when no string matches are found.
- *focused*: Will be shown, when workspace is focused.
- *active*: Will be shown, when workspace is active on its output.
- *urgent*: Will be shown, when workspace has urgent windows.
- *empty*: Will be shown, when workspace is empty.

# EXAMPLES

```
"niri/workspaces": {
    "format": "{icon} {windows}",
    "format-window-separator": "|",
    "window-rewrite-default": "",
    "window-rewrite": {
        "app_id<firefox>": "",
        "app_id<foot>": "",
        "app_id<org.gnome.Nautilus> title<.*Downloads.*>": "",
        "app_id<org.gnome.Nautilus>": ""
    },
    "format-icons": {
        // Named workspaces
        // (you need to configure them in niri)
        "browser": "",
        "discord": "",
        "chat": "<b></b>",

        // Icons by state
        "active": "",
        "default": ""
    }
}
```

```
"niri/workspaces": {
    "format": "{icon}",
    "workspace-taskbar": {
        "enable": true,
        "icon-size": 18
    }
}
```

# Style

- *#workspaces button*
- *#workspaces button.focused*: The single focused workspace.
- *#workspaces button.active*: The workspace is active (visible) on its output.
- *#workspaces button.urgent*: The workspace has one or more urgent windows.
- *#workspaces button.empty*: The workspace is empty.
- *#workspaces button.current_output*: The workspace is from the same output as
  the bar that it is displayed on.
- *#workspaces button#niri-workspace-<name>*: Workspaces named this, or index
  for unnamed workspaces.
- *#workspaces button.niri-workspace*: The main container for the workspace.
- *#workspaces button .niri-taskbar-btn*: The icon buttons within the taskbar.