General

sweets.general({ ... }) configures global compositor behavior. It is where you choose the modifier represented by MOD, the output clear color, the numbered workspace model, and several focus and movement policies.

sweets.general({
  background = "#12121c",
  mod_key = "SUPER",
  workspace_mode = "shared",
  workspace_count = 10,
  workspace_move_follow = false,
  focus_cross_monitor = true,
  move_cross_monitor = true,
  drag_center_cursor = true,
})

Options

The built-in fallback is used when no configuration can be loaded. The standard installed configuration overrides background with "#12121c"; its other general values match the fallbacks above.

background

background is the solid clear color behind windows and desktop surfaces. Use six hexadecimal digits for red, green, and blue, with an optional final two digits for alpha:

sweets.general({
  background = "#1e1e2e",
})

A successful reload applies the new color immediately and redraws the outputs.

mod_key

mod_key chooses what MOD means in every binding specification. It accepts "SUPER" or "ALT" and is case-insensitive.

sweets.general({
  mod_key = "ALT",
})

sweets.bind("MOD+Return", "spawn", "foot")

Here, MOD+Return means Alt+Return. Explicit modifiers such as Ctrl, Shift, Alt, and Super are not changed. Reloading the configuration rebuilds the binding set with the new MOD value.

See Key bindings for the full binding syntax.

workspace_mode

workspace_mode controls how numbered workspaces relate to monitors.

shared

"shared" maintains one logical workspace for each number across the whole session. A numbered workspace can be visible on at most one monitor.

• Selecting a workspace that is already visible focuses its monitor.
• A hidden workspace with windows returns to its remembered or pinned monitor.
• An empty workspace opens on the currently selected monitor.

per_monitor

"per_monitor" maintains a separate workspace for every monitor and number. A workspace-number action normally operates on the selected monitor, so two monitors can each have their own workspace 1.

A monitor pin created with sweets.workspace takes precedence over the selected monitor in either mode. See Workspaces for pinning and workspace-specific configuration.

Changing workspace_mode on reload is supported. Switching to per_monitor keeps existing workspaces on their current or remembered monitors and creates the missing per-monitor workspaces. Switching to shared merges workspaces with equal numbers, preferring the selected monitor's workspace when needed. Windows are preserved during either transition.

workspace_count

workspace_count sets the usable numbered workspace range from 1 through 10. Requests above the configured count are ignored whether they come from a binding, IPC, or a desktop component. Disabled workspaces are also withdrawn from the workspace protocol, so panels stop showing them.

The count and your bindings are independent. If you lower the count to 5, bindings for workspaces 6 through 10 remain defined but do nothing. Keep a generated binding loop within the same range:

sweets.general({
  workspace_count = 5,
})

for i = 1, 5 do
  sweets.bind("MOD+" .. i, "workspace", i)
  sweets.bind("MOD+Shift+" .. i, "workspace_move", i)
end

Lowering the count on reload does not strand windows. Sweets first moves windows from disabled workspaces to the last enabled workspace in the same scope, then withdraws the disabled workspaces. Increasing the count makes the additional workspace numbers available immediately.

workspace_move_follow

workspace_move_follow controls what happens after workspace_move or the IPC move-to-workspace action.

• false: move the window and keep the source workspace selected.
• true: select the resolved destination and keep focus on the moved window.

A reload changes subsequent moves and does not switch the current workspace by itself.

Directional cross-monitor behavior

Sweets first looks for a valid target on the current monitor. The cross-monitor settings control what happens only when no local target exists in the requested direction.

focus_cross_monitor

When enabled, focus_left, focus_right, focus_up, and focus_down may focus a window on the adjacent monitor. When disabled, directional focus stays on the current monitor.

Changing this setting on reload affects the next focus action; it does not move focus immediately.

move_cross_monitor

When enabled, move_left, move_right, move_up, and move_down may carry the focused tiled window to the adjacent monitor's visible workspace. The moved window remains focused. Floating, maximized, and fullscreen windows do not use this fallback.

When disabled, directional movement stops at the monitor edge. Explicit move_output_left, move_output_right, move_output_up, and move_output_down actions remain available regardless of this setting.

Changing this setting on reload affects subsequent moves and does not move a window immediately.

drag_center_cursor

drag_center_cursor applies when a compositor MOD+left-button move starts on a tiled window.

When enabled, Sweets begins the move with the window's outer rectangle centered under the stationary pointer. The move target is not clamped to one output, so the drag overlay can cross monitor boundaries naturally. When disabled, the window keeps the exact point where you grabbed it.

Floating-window moves and moves requested by Wayland or X11 clients always keep their exact grab point. Reloading this setting affects later grabs; an active drag keeps the value that was selected when it began.

Validate and reload

Check the full layered configuration without starting Sweets:

sweets --check-config

Apply a valid change to a running session:

sweets msg reload

If validation fails, Sweets reports the error and keeps the last valid configuration active.