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.

Jay also supports overlay workspaces that render above normal workspaces and can be toggled on and off.

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",
}

The show-workspace action supports several optional fields:

output

The output to create a new workspace on. Has no effect on workspaces that already exist unless move-to-output is also set to true. If multiple outputs match, the first match is used.

move-to-output

Whether to move the workspace to the target output if it already exists on a different output. Default: false.

focus

Whether the workspace grabs the keyboard focus. Default: true.

fallback-output-mode

Which output to use when no explicit output is specified. Either "cursor" or "focus". Default: the global fallback-output-mode setting.

toggle

Whether to hide the workspace if it is already visible. This only has an effect for overlay workspaces. Default: false.

For example, to always show a workspace on a specific output, moving it there if necessary:

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

To switch to a workspace without changing focus:

[shortcuts]
alt-F1 = {
    type = "show-workspace",
    name = "1",
    focus = false,
}

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 using natural ordering. 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.