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",
})| Field | Default | Effect |
|---|---|---|
default | "tile" | Layout for new workspaces |
maximize | "gaps" | Choose how far a maximized window extends |
master | 50 | Master area size in percent, 10–90 |
master_count | 1 | Windows 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_stack | false | centered: keep the master centered with only one other window |
reorder_ratio | 0.3 | How far to drag before windows swap |
floating_placement | "center" | "center" or "cascade" for newly opened floating windows |
floating_step | 50 | Pixels per keyboard move or resize of a floating window |
gaps_step | 5 | Pixels per gaps_grow or gaps_shrink |
cycle | all layouts | Order for cycle_layout |
struts | 0 | Screen 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
| Name | Arrangement |
|---|---|
tile | A master area beside a stack |
monocle | One window at a time, full size |
centered | A centered master with stacks on both sides |
grid | An even grid |
columns | Equal columns, or rows with master_position = "top" |
deck | A master beside one stack window at a time |
dwindle | Each new window splits the last one in half |
scrolling | Columns 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")| Action | Result |
|---|---|
swap_with_master | Swap the window with the master. Press again to swap back |
focus_master | Focus the master. Press again to go back |
rotate_next, rotate_prev | Shift every window one slot, keeping their order |
add_master, remove_master | More or fewer windows in the master area |
add_master and remove_master work in tile, centered, and deck.
new_window
| Value | New 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")| Layout | What resizes |
|---|---|
tile | The master split, or between stack windows |
centered | The master width, or inside one side stack |
grid | Rows and columns |
columns | Between columns |
deck | The master split only |
dwindle | The nearest split |
monocle | Nothing |
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:
| Field | Default | Effect |
|---|---|---|
width | Current width | Content width in logical pixels; values up to 1 are work-area proportions |
height | Current height | Content height, using the same units |
position | Current top-left | An 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",
})| Field | Default | Effect |
|---|---|---|
column_width | 0.5 | New 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_step | 0.1 | Width 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_visible | 0.0 | Scroll to a window the pointer enters once this share of it is visible. 0 never scrolls |
wrap_focus | false | Focus wraps from one end of the strip to the other |
drag_edge_scroll | false | Scroll 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.
| Action | Result |
|---|---|
focus_left, focus_right | Focus the next column |
focus_up, focus_down | Focus within the column |
move_left, move_right | Move the column, or take a stacked window out |
move_up, move_down | Reorder within the column |
consume_or_expel_left, consume_or_expel_right | Join the next column, or leave the current one |
move_column_left, move_column_right | Move the whole column one place |
move_column_first, move_column_last | Move the whole column to either end |
move_column_to | Move the whole column to the given position |
workspace_move_column | Move the whole column to the workspace number given as an argument |
focus_column_first, focus_column_last | Jump to the first or last column |
focus_column | Jump to the column at the given position |
center_visible_columns | Center the fully visible columns as a group |
strip_step | Pan toward the next or previous column |
resize_grow, resize_shrink | Change the column width |
cycle_column_width, cycle_column_width_reverse | Step through column_widths |
cycle_member_size, cycle_member_size_reverse | Cycle the focused window through member_sizes |
reset_member_size | Reset the focused window’s size |
toggle_full_width | Make the column full width, or undo |
expand_column | Fill 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 window | Result |
|---|---|
| Over the middle of a column | It joins that column |
| Near a column's left or right edge | It becomes a new column on that side |
| Between columns | It 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,
})| Field | Default | Effect |
|---|---|---|
inner | 8 | Pixels between windows |
outer | 8 | Pixels around the screen edge |
smart | false | No 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",
})| Field | Default | Effect |
|---|---|---|
width | 2 | Border width in pixels, 0 turns it off |
smart | false | No 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 |
captured | unset | Window being screen-shared |
pinned | unset | Pinned window |
above | unset | Window 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 },
})| Field | Default | Effect |
|---|---|---|
corner_radius | 0 | Rounded corners in pixels |
opacity | 1.0 | Window 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")| Field | Default | Effect |
|---|---|---|
dim | "#000000A6" | Color that darkens the desktop behind it |
blur | false | Blur the desktop behind it. Needs sweets.blur |
hide_on_workspace_change | false | Hide 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.