Sweets

Layout

Tiling layouts, gaps, borders, window corners, and the special workspace

sweets.layout

sweets.layout({
  default = "tile",
  master = 50,
  master_position = "left",
  new_window = "master",
  floating_placement = "center",
})
FieldDefaultEffect
default"tile"Layout for new workspaces
maximize"gaps"Choose how far a maximized window extends
master50Master area size in percent, 10–90
master_count1Windows in the master area, 1–16
master_position"left""left", "right", "top", "bottom", or "auto"
new_window"master"Where new windows go: "master", "stack", or "after_focused"
center_when_single_stackfalsecentered: keep the master centered with only one other window
reorder_ratio0.3How far to drag before windows swap
floating_placement"center""center" or "cascade" for newly opened floating windows
floating_step50Pixels per keyboard move or resize of a floating window
gaps_step5Pixels per gaps_grow or gaps_shrink
cycleall layoutsOrder for cycle_layout
struts0Screen margin no window can use

Each workspace keeps its own layout.

maximize

By default, maximizing keeps the outer gaps and window decorations. Set maximize = "edges" in your sweets.layout table to fill the work area with square corners and no border or shadow.

sweets.layout({ maximize = "edges" })

Layouts

NameArrangement
tileA master area beside a stack
monocleOne window at a time, full size
centeredA centered master with stacks on both sides
gridAn even grid
columnsEqual columns, or rows with master_position = "top"
deckA master beside one stack window at a time
dwindleEach new window splits the last one in half
scrollingColumns on a strip that scrolls (details)

monocle and grid ignore the master settings.

Switching layouts

sweets.bind("MOD+W", "cycle_layout")
sweets.bind("MOD+Shift+W", "cycle_layout_reverse")
sweets.bind("MOD+G", "layout", "grid")

Limit or reorder the cycle:

sweets.layout({ cycle = { "tile", "centered", "monocle" } })

The master area

master_position

Set master_position = "auto" to put the master at the top of a tall work area and on the left of a wide or square one. The master turns when you rotate the monitor or move the workspace to a differently shaped screen.

Move the master area to another side of the screen:

sweets.bind("MOD+I", "cycle_master_position")
sweets.bind("MOD+Shift+I", "cycle_master_position_reverse")

Cycling fixes the side for that workspace. Use reset_layout to restore its configured setting.

Master windows

sweets.bind("MOD+Shift+Return", "swap_with_master")
sweets.bind("MOD+Ctrl+Return", "focus_master")
sweets.bind("MOD+Shift+bracketright", "rotate_next")
sweets.bind("MOD+Shift+bracketleft", "rotate_prev")
sweets.bind("MOD+bracketright", "add_master")
sweets.bind("MOD+bracketleft", "remove_master")
ActionResult
swap_with_masterSwap the window with the master. Press again to swap back
focus_masterFocus the master. Press again to go back
rotate_next, rotate_prevShift every window one slot, keeping their order
add_master, remove_masterMore or fewer windows in the master area

add_master and remove_master work in tile, centered, and deck.

new_window

ValueNew windows open
"master"As the master
"stack"At the end of the stack
"after_focused"Right after the focused window

Floating placement

Floating windows open centered by default. Set floating_placement = "cascade" to offset new windows 32 logical pixels down and right. Placement returns to center when the next step would leave the work area.

Explicit positions, remembered geometry, dialogs and transients keep their placement. Reload affects only new windows.

reorder_ratio

How far you must drag a tiled window into another before they swap, from 0.1 to 0.9. Lower swaps sooner.

Resizing

sweets.bind("MOD+equal", "resize_grow")
sweets.bind("MOD+minus", "resize_shrink")
sweets.bind("MOD+Shift+equal", "resize_grow_vertical")
sweets.bind("MOD+Shift+minus", "resize_shrink_vertical")
sweets.bind("MOD+U", "reset_layout")
sweets.bind("MOD+Shift+U", "reset_all_layouts")
LayoutWhat resizes
tileThe master split, or between stack windows
centeredThe master width, or inside one side stack
gridRows and columns
columnsBetween columns
deckThe master split only
dwindleThe nearest split
monocleNothing

reset_layout puts sizes, gaps, and the master area back to your config. reset_all_layouts does that on every workspace.

Floating windows

sweets.bind("MOD+Ctrl+Alt+Left", "move_floating_left")
sweets.bind("MOD+Ctrl+Alt+Right", "move_floating_right")
sweets.bind("MOD+Ctrl+Alt+Up", "move_floating_up")
sweets.bind("MOD+Ctrl+Alt+Down", "move_floating_down")
sweets.bind("MOD+Ctrl+equal", "resize_floating_grow")
sweets.bind("MOD+Ctrl+minus", "resize_floating_shrink")

Each press moves or resizes by floating_step pixels.

Add "edge" to move to the next window or screen edge. grow_floating_* grows one side instead.

sweets.bind("MOD+Ctrl+Alt+H", "move_floating_left", "edge")
sweets.bind("MOD+Ctrl+Alt+Shift+H", "grow_floating_left", "edge")

These actions stay on the current screen and honor snap.respect_gaps Size limits still apply. Pointer snapping can stay off

Set floating size and position

sweets.bind("MOD+Ctrl+Alt+P", "set_floating_geometry", {
    width = 0.7,
    height = 480,
    position = "top-right",
})

This makes the focused floating window 70% of the work area wide and 480 pixels tall, in the top-right corner. Panels and struts shrink the work area. Borders are extra.

Supply at least one field:

FieldDefaultEffect
widthCurrent widthContent width in logical pixels; values up to 1 are work-area proportions
heightCurrent heightContent height, using the same units
positionCurrent top-leftAn anchor, coordinate pair, anchored offset, or "pointer", as in window rules

Sizes must be positive. Size limits still apply before placement. With keep_aspect_ratio, one dimension adjusts the other; both fit the current ratio inside the requested box.

The window stays on the same screen with its pin state preserved. Tiled, fullscreen, maximized, and actively grabbed windows ignore the action. Mouse/scroll bindings and action lists accept the same preset.

Struts

Struts keep a margin on a screen edge free of windows, for example around a notch or bezel:

sweets.layout({ struts = { top = 32 } })

Use one number for all edges, or name top, bottom, left, and right. Struts add to the space panels already reserve. A monitor rule can set its own.

Scrolling

scrolling places each window in a column on a strip. The strip can be wider than the screen and scrolls to show the focused column.

sweets.layout({ default = "scrolling" })

sweets.scrolling({
  column_width = 0.5,
  column_widths = { 0.333, 0.5, 0.667, 1.0 },
  member_sizes = { 0.3333, 0.5, 0.6667, 1.0 },
  focus = "fit",
  direction = "right",
})
FieldDefaultEffect
column_width0.5New column width as a share of the screen, or pixels above 1
column_widths{ 0.333, 0.5, 0.667, 1.0 }Widths for cycle_column_width
member_sizes{ 0.3333, 0.5, 0.6667, 1.0 }Window sizes for cycle_member_size
resize_step0.1Width change per resize_grow or resize_shrink
focus"fit""fit" scrolls as little as needed, "center" centers the column, "center_on_overflow" centers only when it can't fit
follow_min_visible0.0Scroll to a window the pointer enters once this share of it is visible. 0 never scrolls
wrap_focusfalseFocus wraps from one end of the strip to the other
drag_edge_scrollfalseScroll while holding a window or Wayland data drag near the outer edge
single_column"fill"A lone column: "fill", "center", or "start"
narrow_strip"center"Columns narrower than the screen: "center" or "start"
direction"right"Strip direction: "right", "left", "down", "up", or "auto"

A new window opens as a column after the focused one. Clicking a partly hidden window scrolls it into view.

Defaults by monitor and workspace

sweets.monitor("DP-1", {
  scrolling = { column_width = 0.333, column_widths = { 0.25, 0.333, 0.5 } },
})
sweets.workspace(8, { layout = "scrolling", scrolling = { focus = "center" } })

You can set column_width, column_widths, focus, single_column, and narrow_strip here. Each field uses the workspace value first, then the monitor value, then sweets.scrolling. A special workspace uses its host monitor's settings.

Columns that follow the default width pick up the new width when their workspace moves to another monitor. Columns you resized keep their chosen share or logical pixel width.

Columns

A column can hold several windows stacked top to bottom.

ActionResult
focus_left, focus_rightFocus the next column
focus_up, focus_downFocus within the column
move_left, move_rightMove the column, or take a stacked window out
move_up, move_downReorder within the column
consume_or_expel_left, consume_or_expel_rightJoin the next column, or leave the current one
move_column_left, move_column_rightMove the whole column one place
move_column_first, move_column_lastMove the whole column to either end
move_column_toMove the whole column to the given position
workspace_move_columnMove the whole column to the workspace number given as an argument
focus_column_first, focus_column_lastJump to the first or last column
focus_columnJump to the column at the given position
center_visible_columnsCenter the fully visible columns as a group
strip_stepPan toward the next or previous column
resize_grow, resize_shrinkChange the column width
cycle_column_width, cycle_column_width_reverseStep through column_widths
cycle_member_size, cycle_member_size_reverseCycle the focused window through member_sizes
reset_member_sizeReset the focused window’s size
toggle_full_widthMake the column full width, or undo
expand_columnFill the free space on screen
sweets.bind("MOD+Comma", "consume_or_expel_left")
sweets.bind("MOD+Period", "consume_or_expel_right")
sweets.bind("MOD+Home", "focus_column_first")
sweets.bind("MOD+End", "focus_column_last")
sweets.bind("MOD+Alt+Home", "move_column_first")
sweets.bind("MOD+Ctrl+2", "focus_column", 2)
sweets.bind("MOD+Alt+C", "center_visible_columns")
sweets.bind("MOD+Ctrl+R", "cycle_column_width")
sweets.bind("MOD+Ctrl+F", "toggle_full_width")

center_visible_columns keeps the same focus and column widths. If the focused column is clipped or offscreen, it centers just that column.

Use strip_step to look along the strip without moving keyboard focus. It works in strip order and stops at either end.

sweets.bind_scroll("MOD+Alt+ScrollDown", "strip_step", "next")
sweets.bind_scroll("MOD+Alt+ScrollUp", "strip_step", "prev")
sweets.bind("MOD+Alt+F9", "strip_step", "next")
sweets.bind("MOD+Alt+F10", "strip_step", "prev")

member_sizes takes 1–8 different sizes. Use 0.05–1 for a share of the space, or 2–16384 for pixels, borders included. It sets height in horizontal strips and width in vertical strips.

Cycling starts from the size closest to the current one. Sizes respect window minimums and leave room for neighbours. Reset restores the focused window’s default share.

Member-size bindings do nothing for single-window columns, tabs, floating windows, or maximized/fullscreen windows.

To turn a column into tabs, see Tabs. The column_width window rule opens an app at its own width.

Dragging into columns

Drop the windowResult
Over the middle of a columnIt joins that column
Near a column's left or right edgeIt becomes a new column on that side
Between columnsIt becomes a new column there

Direction

"auto" grows the strip down in a tall work area and right in a wide or square one. After turning it by hand, use reset_layout to restore the configured direction.

"down" and "up" stack columns vertically. Then up and down move between columns, and left and right move within one. cycle_master_position turns the strip on the current workspace.

sweets.gaps

sweets.gaps({
  inner = 8,
  outer = 8,
  smart = true,
})
FieldDefaultEffect
inner8Pixels between windows
outer8Pixels around the screen edge
smartfalseNo outer gap with only one window

outer can also name each edge. An omitted edge is 0:

sweets.gaps({ outer = { top = 4, bottom = 12, left = 8, right = 8 } })

Change gaps on the fly with gaps_grow, gaps_shrink, and toggle_gaps. Pass "outer" to change the outer gap. A reload resets them.

sweets.border

sweets.border({
  width = 4,
  focused = "#C27AFF",
  unfocused = "#333338",
})
FieldDefaultEffect
width2Border width in pixels, 0 turns it off
smartfalseNo border with only one window
focused"#C27AFF"Focused window
unfocused"#333338"Other windows
urgent"#F7768E"Window asking for attention
unresponsive"#E0AF68"Window that stopped responding
capturedunsetWindow being screen-shared
pinnedunsetPinned window
aboveunsetWindow kept above others

Colors use #RRGGBB or #RRGGBBAA. The installed config uses width = 4.

For a gradient, give a list of up to eight colors and an angle in degrees:

sweets.border({
  focused = { "#C27AFF", "#7AA2F7", angle = 45 },
})

A window rule can change or remove the border for one app.

sweets.window

sweets.window({
  corner_radius = 12,
  opacity = { focused = 1.0, unfocused = 0.92 },
})
FieldDefaultEffect
corner_radius0Rounded corners in pixels
opacity1.0Window opacity, or focused and unfocused values

The installed config uses corner_radius = 12. Round only some corners with a table. Omitted corners are square:

sweets.window({ corner_radius = { top_left = 16, top_right = 16 } })

Fullscreen windows are always square.

sweets.layout_style

Change the look of tiled windows for one layout:

sweets.layout_style("tile", {
  border = { width = 2 },
  gaps = { inner = 4, outer = 12 },
  window = { corner_radius = 8 },
})

sweets.layout_style("monocle", {
  border = { width = 0 },
  window = { corner_radius = 0 },
})

It takes border.width, gaps.inner, gaps.outer, gaps.smart, and window.corner_radius. Anything you leave out uses the global value.

Monitors and workspaces accept the same fields. When several apply, the most specific wins: layout style, then workspace, then monitor, then global.

sweets.special

Special workspaces show a separate collection of windows over your desktop.

sweets.special({
  dim = "#000000A6",
  blur = false,
  hide_on_workspace_change = false,
})

sweets.bind("MOD+S", "special_toggle")
sweets.bind("MOD+Shift+S", "special_move")
sweets.bind("MOD+Ctrl+M", "special_toggle", "music")
FieldDefaultEffect
dim"#000000A6"Color that darkens the desktop behind it
blurfalseBlur the desktop behind it. Needs sweets.blur
hide_on_workspace_changefalseHide the special workspace when you change workspaces on its monitor

special_toggle shows or hides it. special_move sends the focused window there. Give a name to keep several. See Workspaces.

Turn on hide_on_workspace_change to leave the special workspace behind when switching tasks. Its windows stay there for the next special_toggle. Switching monitors alone keeps it shown.

On this page