Overlays

Overlays are workspaces that render on top of the normal workspace and layer-shell surfaces. They are useful for scratch pads, floating terminals, quick-access tools, or any set of windows you want to summon and dismiss without disturbing your main workspace layout. Other compositors call this concept special workspaces or scratchpads.

Defining an Overlay

The show-overlay and toggle-overlay actions automatically set the workspace type to overlay. A shortcut binding is all you need:

[shortcuts]
alt-s = { type = "toggle-overlay", name = "scratchpad" }

If you want to configure additional workspace properties, you can also declare the overlay explicitly in the [workspaces] table:

[workspaces."scratchpad"]
type = "overlay"

Overlays and normal workspaces share the same namespace. A workspace can only be one type at a time.

Showing an Overlay

Use the show-overlay action to display an overlay on the current output:

[shortcuts]
alt-s = { type = "show-overlay", name = "scratchpad" }

This creates the overlay if it does not exist and moves it to the output that currently has focus. If the overlay is already visible on another output, it moves to the current one.

show-overlay is a convenience alias for show-workspace with move-to-output set to true and toggle set to false. It accepts the same optional fields as show-workspace (output, focus, fallback-output-mode).

Toggling an Overlay

Use the toggle-overlay action to show or hide an overlay:

[shortcuts]
alt-s = { type = "toggle-overlay", name = "scratchpad" }

If the overlay is not visible, it is shown on the current output. If it is already visible, it is hidden.

toggle-overlay is a convenience alias for show-workspace with move-to-output set to false and toggle set to true.

Hiding Overlays

There are several ways to hide overlays:

hide-overlay

Hides a specific overlay by name.

hide-overlays

Hides all visible overlays on all outputs.

[shortcuts]
alt-shift-s = { type = "hide-overlay", name = "scratchpad" }
alt-Escape  = "hide-overlays"

You can also middle-click an overlay’s tab in the bar to hide it.

When an overlay is hidden, its windows are preserved. Showing the overlay again restores them. If an overlay is hidden while empty, it is automatically destroyed. Hidden overlays with windows are not shown in the bar. You can use the control center Workspaces pane to see all existing workspaces, including hidden overlays.

Behavior

Overlay workspaces differ from normal workspaces in several ways:

• Rendering order. Overlays render above layer-shell surfaces. This means an overlay is always on top of panels, status bars, and other layer-shell clients.

• Floating by default. Windows opened while an overlay is active default to floating rather than tiled. You can still tile windows within an overlay using the normal tiling actions.

• Overlay icon. Windows in an overlay display a diamond-shaped icon in their title bar to distinguish them from windows in normal workspaces.

• One per output. Each output can display at most one overlay at a time. Showing a different overlay on an output replaces the current one.

• Bar tab. A visible overlay appears as a tab in the bar, after the normal workspace tabs. It is always highlighted with the focused title background color.

Moving Windows from and to Overlays

The move-to-workspace action works with overlays just like with normal workspaces. You can also use move-left, move-right, etc. to move a window to an adjacent output’s overlay.

You can move floating windows between normal workspaces and overlays by dragging their title bar. When you drop a floating window on an output, it lands on the overlay if one is visible, or on the normal workspace otherwise. To move a floating window out of an overlay, either drag it to an output that has no overlay visible, or hide the overlay while the mouse button is still held down.

Tiled windows can also be moved by dragging their title bar. Drop a tile onto the overlay’s bar tab to move it into the overlay, or onto a normal workspace tab to move it out.

Hold-to-Show

Using complex shortcuts, you can show an overlay while a key is held and hide it on release:

[complex-shortcuts.alt-s]
action = { type = "show-overlay", name = "scratchpad" }
latch = { type = "hide-overlay", name = "scratchpad" }

Using show-workspace Directly

The show-overlay and toggle-overlay actions are convenience aliases. You can use show-workspace directly with overlay workspaces for full control over the toggle and move-to-output fields. Unlike the overlay actions, show-workspace does not automatically set the workspace type, so you must define the overlay in the [workspaces] table:

[shortcuts]
# Toggle the overlay and always move it to the current output
alt-s = {
    type = "show-workspace",
    name = "scratchpad",
    toggle = true,
    move-to-output = true,
}

The toggle field has no effect on normal workspaces.