Skip to main content
When working with layer-shell components (bars, launchers, etc.) in niri, there are several important behaviors to keep in mind.

​
Full-Screen Window Behavior

When a full-screen window is active and covers the entire screen, it will render above the top layer, and it will be prioritized for keyboard focus.
If your launcher uses the top layer, and you try to run it while looking at a full-screen window, it won’t show up.
Only the overlay layer will show up on top of full-screen windows.

​
Example Scenario

1

Full-screen window is active

A video player or game is running in full-screen mode.
2

Launch a top-layer component

You try to open a launcher that uses the top layer.
3

Component doesn't appear

The launcher won’t be visible because the full-screen window renders above it.
4

Solution

Use the overlay layer for components that need to appear over full-screen windows.

​
Keyboard Focus Behavior

​
On-Demand Focus

Components on the bottom and background layers will receive on-demand keyboard focus as expected.
This means they can receive focus when you interact with them directly.

​
Exclusive Focus

Components on the bottom and background layers will only receive exclusive keyboard focus when there are no windows on the workspace.
This ensures that regular windows take priority for keyboard input when they’re present.

​
Overview Behavior

When opening the Overview, components behave differently based on their layer.

​
Layer Behavior in Overview

Components on these layers will:
  • Zoom out together with the workspaces
  • Remain attached to their respective workspaces
  • Move with the workspace during transitions

​
Bar Placement Recommendation

If you want the bar to remain on top during Overview, put it on the top layer.

​
Layer Selection Guide

Choose the appropriate layer based on your component’s needs:
Component TypeRecommended LayerReason
Status barTopStays visible during Overview
LauncherOverlayCan appear over full-screen windows
Desktop iconsBackgroundZooms with workspace in Overview
DockBottomReceives focus when no windows present
NotificationsOverlayAppears above all content
These are recommendations based on typical use cases. Your specific needs may vary.

Build docs developers (and LLMs) love

Get started for freeTalk to us