taskbar

Icon-only running application list, with optional pinned apps on the flat strip. By default it follows the bar’s monitor (only windows the compositor associates with that monitor). Enable Show all monitors when you use one bar for everything but still want to see and focus apps on other monitors.

Set prefer_symbolic_icons = true to try an icon theme’s -symbolic application icon first and fall back to the regular icon when no symbolic variant exists. Symbolic icons inherit the taskbar widget’s icon/foreground color. Regular fallback icons keep their normal appearance unless global [shell.app_icon_colorize] is enabled, in which case they use the existing app-icon colorization pipeline (see Shell → App icon colorization).

Left-click an icon to focus that window (or launch a pinned app that is not running). Middle-click an icon to close that window (the active window when a grouped or pinned multi-window tile represents several). Middle-click in the gaps between icons still opens the taskbar widget settings. The active window shows a small primary dot under the icon. When grouped app collapsing is enabled, multi-window app tiles also show compact right-edge dots over the icon. Pinned apps with multiple windows use the same dots and left-click cycles their windows.

On Umbriel, KDE Plasma, and labwc, clicking a single-window icon restores a minimised window, focuses an unfocused window, or minimises the focused window when the compositor allows it. Grouped and pinned icons representing multiple windows continue cycling their windows. Scrolling between tasks focuses or restores them.

Minimised windows stay in the taskbar and window counts. A contrasting minus badge at the bottom-left of an icon marks it when every window it represents is minimised, even with show_active_indicator = false. Mixed groups keep their usual icon appearance; their tooltip reports how many windows are minimised. Right-click for per-window Minimise or Restore actions when available. These features require a connected compositor backend reporting minimise state; no additional configuration is needed.

Pinned apps (pinned) keep desktop entries on the taskbar when they are not running. Matching uses the same desktop-entry rules as the dock. Pinned apps appear first (in list order), collapsed to one icon per app; other running windows follow as usual. Right-click an icon and choose Pin / Unpin to update the list. Non-running pins are dimmed by pinned_opacity (default 0.5). Pins are only used on the flat strip; when group_by_workspace is on they are ignored (settings hide the list, and pin menu actions are unavailable).

Show running (show_running, default true) keeps windows that are not in pinned on the flat strip; set it to false for a pinned-only strip. Keep at least one pin, or a pinned-only strip with an empty pinned list is blank and still reserves its bar slot. Ignored while group_by_workspace is on.

Only active workspace limits the list to windows the shell can place on a workspace that is currently active on its monitor (same idea as the v4 taskbar option). It works with or without group_by_workspace; with grouping, inactive workspace capsules are omitted.

Workspace grouping (group_by_workspace and related options) needs per-window workspace assignment from the compositor, not just a workspace list. Without it, the taskbar stays flat and those settings are hidden in the GUI (config keys are accepted but ignored). LabWC is a common example (discussion #2924); use the workspaces widget for switching there.

When group_by_workspace is enabled, workspace disc indicators (the small numbered/name tags) and optional group capsules (the background around each workspace’s icon row) use the taskbar widget’s resolved capsule_radius. On niri, named workspaces use their names for these tags; unnamed workspaces use their numeric index. Set [widget.taskbar].capsule_radius for just the taskbar, or [bar.<name>].capsule_radius as the bar default. Set show_workspace_label = false to hide workspace disc indicators (icons only). Set workspace_group_capsule = false to drop the group background/border while keeping grouping and disc labels. With grouping, workspace_group_content chooses what each capsule shows for its windows: icons (default app tiles), count (window count), or dots (one dot per window; the focused window uses active_indicator_color when show_active_indicator is on). Dot mode shows at most five dots and a +N overflow when there are more windows. Left-click on count/dots activates that workspace. group_single_icon_per_app only applies when content is icons.

On supported compositors, minimised windows use hollow dots in workspace_group_content = "dots". Workspace counts still include them, and count/dot tooltips report the minimised count. A workspace containing minimised windows remains occupied.

Setting	Type	Default	Description
pinned	array of string	[]	Desktop entry IDs to keep on the flat taskbar when not running. Ignored while group_by_workspace is on.
pinned_opacity	float	0.5	Opacity multiplier for pinned apps that are not running. Settings UI shows this only when the pin list is non-empty (and grouping is off).
show_running	bool	true	Show running windows that are not in pinned. Set false for a pinned-only strip; with an empty pinned list the strip is empty but keeps its bar slot. Ignored while group_by_workspace is on.
group_by_workspace	bool	false	Group icons into workspace capsules when per-window workspace assignment is available.
show_all_outputs	bool	false	Include windows from all monitors. With group_by_workspace, workspaces from every monitor are merged; capsule badges use tag·n (workspace tag, middle dot, monitor index in bar monitor order) when there is more than one monitor.
only_active_workspace	bool	false	Show only windows on the active workspace for each relevant monitor. Depends on compositor workspace data; if a window’s workspace cannot be resolved, it is still shown.
hidden_workspaces	array of string	[]	Workspace names whose windows, and capsules when group_by_workspace is on, are left out of the taskbar. A hidden workspace still shows while it is active. Use it for a stash workspace, such as a named niri workspace that apps wait on until they are brought into view. Depends on compositor workspace data.
icon_scale	float	1.0	Scale taskbar application icons relative to their default size. Values from 0.1 to 2.0 are accepted; larger icons remain constrained by the bar thickness.
prefer_symbolic_icons	bool	false	Prefer -symbolic application icons from the active icon theme and fall back to regular icons. Symbolic icons use the taskbar widget icon/foreground color; regular fallbacks still honor global app-icon colorization.
item_spacing	int	4	Space between taskbar items in logical pixels when workspace grouping is off. Values from 0 to 48 are accepted.
show_window_title	bool	false	Show each window title next to its icon on horizontal bars. Available only when workspace grouping is off.
window_title_max_width	int	100	Maximum width of each window title in pixels when titles are enabled.
taskbar_max_width	int	8192	Total taskbar width budget in pixels; titles shrink to fit and disappear when space is too narrow.
show_workspace_label	bool	true	When group_by_workspace is on, show the workspace tag pill on each capsule. Set false for groups without the label.
minimal	bool	false	With workspace grouping and labels enabled, draw text-only labels without colored disc backgrounds. Labels use the focused, occupied, empty, and urgent colors.
workspace_label_placement	string	corner	With grouping: corner, centered (on the pill edge), or inside (first tile in the pill). Requires show_workspace_label.
hide_empty_workspaces	bool	false	When group_by_workspace is on, do not show capsules for workspaces that have no windows in the taskbar list.
workspace_group_capsule	bool	true	Draw the background/border capsule around each workspace group. Set false for grouped icons and labels only.
workspace_group_content	string	icons	With grouping: icons (app tiles), count (window count), or dots (up to five dots per group, then +N for the rest).
workspace_group_active_border_color	string	"primary"	Border color of the active workspace group. Accepts a color role or a fixed hex color.
workspace_group_inactive_border_color	string	"outline_variant"	Border color of inactive workspace groups. Accepts a color role or a fixed hex color.
group_single_icon_per_app	bool	false	With group_by_workspace and workspace_group_content = icons, collapse multiple windows of the same app into one tile per workspace group. Left-click cycles that app’s windows; right-edge overlay dots indicate multiple windows.
show_active_indicator	bool	true	Show a small dot below the active window icon in the taskbar. With workspace_group_content = dots, highlights the focused window’s dot instead.
active_indicator_color	string	"primary"	Color of the active window indicator (dot, title underline, or focused dot in dots mode). Accepts a color role or a fixed hex color. Requires show_active_indicator.
active_opacity	float	1.0	Opacity of the icon for the active (focused) window.
inactive_opacity	float	1.0	Opacity of icons for inactive (unfocused) windows.
focused_color	string	"primary"	Workspace disc fill when active (same roles as the workspaces widget)
occupied_color	string	"secondary"	Workspace disc fill when occupied
empty_color	string	"secondary"	Workspace disc fill when empty (shown at reduced opacity)
urgent_color	string	"error"	Workspace disc fill when urgent
focused_output_only	bool	false	Only highlight the active workspace on the monitor that has keyboard or pointer focus: its workspace disc uses the focused color and its group capsule the stronger fill and border. Active workspaces on other monitors use the occupied color and the inactive capsule style. Requires group_by_workspace = true.

[widget.taskbar]
pinned = ["firefox", "code", "kitty"]
pinned_opacity = 0.5
show_running = true
icon_scale = 1.0
prefer_symbolic_icons = true
item_spacing = 4  # Flat taskbar only; ignored when workspace grouping is enabled
group_by_workspace = true
show_all_outputs = true
only_active_workspace = true
hidden_workspaces = ["scratch"]
show_workspace_label = true
workspace_label_placement = "corner"
hide_empty_workspaces = true
workspace_group_capsule = true
workspace_group_content = "icons"
workspace_group_active_border_color = "primary"
workspace_group_inactive_border_color = "outline_variant"
group_single_icon_per_app = true
show_active_indicator = true
active_indicator_color = "primary"
active_opacity = 1.0
inactive_opacity = 1.0
focused_color = "primary"
occupied_color = "secondary"
empty_color = "secondary"
urgent_color = "error"
focused_output_only = false  # true = only the focused monitor highlights its active workspace