Workspaces

Workspaces are virtual desktops that group windows together. Each workspace lives on an output (monitor) and contains its own tiling layout. Jay creates workspaces on demand and automatically manages them when monitors are connected or disconnected.

Switching Workspaces

Use the show-workspace action to switch to a workspace. In the default configuration, alt-F1 through alt-F12 switch to workspaces named “1” through “12”:

[shortcuts]
alt-F1  = { type = "show-workspace", name = "1" }
alt-F2  = { type = "show-workspace", name = "2" }
alt-F3  = { type = "show-workspace", name = "3" }
# ... and so on through alt-F12

If the workspace does not yet exist, it is created on the output that currently contains the cursor. You can override this by specifying an output:

[shortcuts]
alt-F1 = {
    type = "show-workspace",
    name = "1",
    output.name = "left",
}

You can also scroll over the bar to cycle through workspaces on that output.

Moving Windows to Workspaces

Use the move-to-workspace action to send the focused window to a different workspace. The default bindings are alt-shift-F1 through alt-shift-F12:

[shortcuts]
alt-shift-F1  = { type = "move-to-workspace", name = "1" }
alt-shift-F2  = { type = "move-to-workspace", name = "2" }
alt-shift-F3  = { type = "move-to-workspace", name = "3" }
# ... and so on through alt-shift-F12

You can also drag a tile’s title onto a workspace tab in the bar to move it to that workspace. Dragging a tile onto the bar outside any workspace tab creates a new workspace for it.

Moving Workspaces Between Outputs

The move-to-output action moves a workspace to a different output. You can target the output by name or by direction:

[shortcuts]
# Move the current workspace to a named output
alt-o = { type = "move-to-output", output.name = "right" }

# Move the current workspace in a direction
logo-ctrl-shift-Right = {
    type = "move-to-output",
    direction = "right",
}
logo-ctrl-shift-Left = {
    type = "move-to-output",
    direction = "left",
}
logo-ctrl-shift-Up = {
    type = "move-to-output",
    direction = "up",
}
logo-ctrl-shift-Down = {
    type = "move-to-output",
    direction = "down",
}

You can also move a specific workspace by name:

[shortcuts]
alt-o = {
    type = "move-to-output",
    workspace = "1",
    output.name = "right",
}

If workspace is omitted, the currently active workspace is moved.

Workspace Display Order

Workspaces appear as tabs in the bar. Their order can be configured in two modes:

• manual (default) – workspaces appear in the order they were created and can be reordered by dragging their titles in the bar.
• sorted – workspaces are sorted alphabetically. Dragging to reorder is disabled.

Set the order in your configuration:

workspace-display-order = "sorted"

You can also change this at runtime in the control center.

Hot-Plug and Hot-Unplug

Jay handles monitor connections gracefully:

• When a monitor is unplugged, its workspaces are automatically migrated to one of the remaining monitors.
• When the monitor is plugged back in, those workspaces are restored to it.

This means you never lose your workspace layout when docking or undocking a laptop.

Workspace Capture

By default, newly created workspaces can be captured for screen sharing. You can disable this globally:

workspace-capture = false

When workspace capture is enabled, screen-sharing applications can share individual workspaces (in addition to full outputs and individual windows). See Screen Sharing for more details.

Matching Windows by Workspace

In window rules, you can match windows based on the workspace they are on:

[[windows]]
match.workspace = "music"
action = "enter-fullscreen"

The workspace-regex field is also available for pattern matching:

[[windows]]
match.workspace-regex = "^(music|video)$"
action = "enter-fullscreen"

Since window rules are reactive, these rules are re-evaluated whenever a window moves to a different workspace.