hyprland-workspaces

Hyprland workspace indicators with click-to-switch.

Add it to your layout with hyprland-workspaces:

bar:
  layout:
    - monitor: "*"
      right: [hyprland-workspaces]

General

Field	Type	Default	Description
min-workspace-count	u8	0	Minimum number of workspace buttons to display.
monitor-specific	bool	true	Show only workspaces belonging to the bar's monitor.
show-special	bool	true	Include special workspaces (scratchpads) in the display.
urgent-show	bool	true	Pulse animation on workspaces with urgent windows.
urgent-mode	UrgentMode	"workspace"	Where the urgent pulse is applied.
display-mode	DisplayMode	"label"	What identifies each workspace button.
label-use-name	bool	false	Use workspace name instead of number when displaying labels.
numbering	Numbering	"absolute"	How workspace numbers are displayed.
divider	string	" "	Text separator between workspace identity and app icons.
app-icons-show	bool	false	Show application icons for windows in each workspace.
app-icons-dedupe	bool	true	Deduplicate application icons within a workspace.
app-icons-fallback	string	"ld-app-window-symbolic"	Fallback icon for applications not matched by app-icon-map.
app-icons-empty	string	"ld-minus-symbolic"	Icon shown for empty workspaces when app-icons-show is enabled.
icon-gap	Size	0.3	Gap between app icons within a workspace button.
workspace-padding	Size	0.5	Padding for workspace content along the bar direction. Accepts a scale multiplier or pixels (e.g. "8px").
icon-size	Size	1	Workspace icon size. Accepts a scale multiplier or pixels (e.g. "16px").
label-size	Size	1	Workspace label and divider size. Accepts a scale multiplier or pixels (e.g. "16px").
workspace-ignore	array of string	[]	Workspaces to hide from the display.
active-indicator	ActiveIndicator	"background"	Visual indicator for the active workspace.
highlight-active-on-other-monitor	bool	true	Highlight workspaces active on other monitors with a different color.
active-color	ColorValue	"accent"	Color for the active (focused) workspace.
occupied-color	ColorValue	"fg-muted"	Color for occupied workspaces (has windows but not focused).
empty-color	ColorValue	"fg-subtle"	Color for empty workspaces.
container-bg-color	ColorValue	"bg-surface-elevated"	Background color for the workspaces container.
border-show	bool	false	Display border around the workspaces container.
border-color	ColorValue	"border-default"	Border color for the workspaces container.
active-on-other-monitor-color	ColorValue	"accent"	Active on other minitor indicator color.
workspace-map	WorkspaceMap	{}	Per-workspace icon and color overrides.
app-icon-map	map of string	{}	Application icon mapping with glob pattern support.
left-click	WorkspaceClickAction	"focus:this"	Action on left-clicking a workspace. Default focuses it.
middle-click	WorkspaceClickAction	""	Action on middle-clicking a workspace.
right-click	WorkspaceClickAction	""	Action on right-clicking a workspace.
scroll-up	WorkspaceClickAction	"focus:previous"	Action on scrolling up over the module. Default focuses the previous workspace.
scroll-down	WorkspaceClickAction	"focus:next"	Action on scrolling down over the module. Default focuses the next workspace.

More about min-workspace-count

When set to 0 (default), only active and occupied workspaces are shown. When set to N, at least N buttons are always visible, with empty ones using empty-color styling.

More about monitor-specific

When true, each bar shows only its monitor's workspaces. When false, all workspaces from all monitors are shown.

More about show-special

Special workspaces have negative IDs in Hyprland.

More about urgent-show

When a window requests attention (e.g., terminal bell), the workspace button pulses until you switch to it.

More about urgent-mode

• workspace: Entire workspace pulses (default)
• application: Only the app icon(s) belonging to the urgent window pulse, falling back to workspace when app icons are disabled

More about display-mode

• label: Shows workspace number (or name if label-use-name is true)
• icon: Shows icon from workspace-map (falls back to label if unmapped)
• none: Shows nothing - only app icons visible

More about label-use-name

Only applies when display-mode: label or as fallback for unmapped workspaces in display-mode: icon.

More about numbering

• absolute: Show actual Hyprland workspace IDs (1, 2, 3, 4, 5, 6...)
• relative: Show numbers relative to monitor's starting workspace. If a monitor has workspaces 4, 5, 6 assigned, they display as 1, 2, 3. Useful when keybinds use per-monitor numbering.

More about divider

Only shown when both display-mode is not none and app-icons-show is enabled. Common values: "|", "·", "-".

More about app-icons-show

When enabled, displays icons for running applications. Icons are resolved via app-icon-map configuration.

More about app-icons-dedupe

When true, shows only one icon per unique window class. When false, shows an icon for every window.

More about app-icons-empty

When a workspace has no windows but is displayed (via min-workspace-count), this icon appears as a placeholder.

More about icon-gap

Only applies to spacing between app icons.

More about workspace-padding

For horizontal bars, controls horizontal (left/right) padding. For vertical bars, controls vertical (top/bottom) padding.

More about icon-size

Applies to workspace identity icons and custom icons from workspace-map.

More about label-size

Applies to workspace number/name labels and the divider text.

More about workspace-ignore

Glob patterns matching workspace IDs. Examples:

• "10" - hide workspace 10
• "1?" - hide workspaces 10-19

More about highlight-active-on-other-monitor

When true, workspaces active on a different monior are highlicted differently. When false, workspaces active on a another monitor are not specially highlighted.

This setting only makes sense when monitor-specific is false.

More about active-color

Applied to icons and labels. In background indicator mode, also used as the button background.

More about occupied-color

Applied to icons and labels.

More about empty-color

Applied to the empty placeholder icon and labels.

More about active-on-other-monitor-color

Only applies when highlight-active-on-other-monitor is true.

More about workspace-map

Keys are workspace IDs (use negative for special workspaces).

Example

modules:
  hyprland-workspaces:
    workspace-map:
      "1": {icon: ld-globe-symbolic, color: "#4a90d9"}
      "2": {icon: ld-terminal-symbolic}

More about app-icon-map

Maps window class or title to symbolic icon names. Supports:

• No prefix: Matches window class (e.g., "*firefox*")
• class: prefix: Explicit class match (e.g., "class:org.mozilla.*")
• title: prefix: Matches window title (e.g., "title:*YouTube*")

User mappings are merged with built-in defaults for common applications.

Example

modules:
  hyprland-workspaces:
    app-icon-map:
      "*firefox*": ld-globe-symbolic
      "title:*YouTube*": ld-youtube-symbolic

Default configuration

modules:
  hyprland-workspaces:
    min-workspace-count: 0
    monitor-specific: true
    show-special: true
    urgent-show: true
    urgent-mode: workspace
    display-mode: label
    label-use-name: false
    numbering: absolute
    divider: ' '
    app-icons-show: false
    app-icons-dedupe: true
    app-icons-fallback: ld-app-window-symbolic
    app-icons-empty: ld-minus-symbolic
    icon-gap: 0.30000001192092896
    workspace-padding: 0.5
    icon-size: 1.0
    label-size: 1.0
    workspace-ignore: []
    active-indicator: background
    highlight-active-on-other-monitor: true
    active-color: accent
    occupied-color: fg-muted
    empty-color: fg-subtle
    container-bg-color: bg-surface-elevated
    border-show: false
    border-color: border-default
    active-on-other-monitor-color: accent
    workspace-map: {}
    app-icon-map: {}
    left-click: focus:this
    middle-click: ""
    right-click: ""
    scroll-up: focus:previous
    scroll-down: focus:next