Sweets

Key Bindings

Bind keys and key sequences to Sweets actions

sweets.bind(keys, action, argument, options) runs an action when you press keys. argument and options are optional.

sweets.bind("MOD+Return", "launch_terminal")
sweets.bind("MOD+Q", "close")
sweets.bind("MOD+2", "workspace", 2)
sweets.bind("MOD+B f", "spawn", { "firefox" })

For mouse buttons and scrolling, see Mouse Bindings.

Keys

Join modifiers and one key with +:

MOD+Shift+Return
Ctrl+Alt+Delete
XF86AudioMute
MOD+code:51
ModifierMeaning
MODYour mod_key
Ctrl, Shift, AltAs named
SuperLogo / Windows key
AltGrXKB level 3
ISO_Level5_ShiftXKB level 5
  • Key names are XKB keysyms: q, Return, space, equal, XF86AudioRaiseVolume. Names are case-insensitive.
  • q and Q are the same key. Add Shift if you mean Shift.
  • code:N matches a physical key whatever your layout. Find N with wev.
  • Modifiers must match exactly. Caps Lock and Num Lock are ignored.
  • Letter bindings keep working when you switch keyboard layouts.

Bind a symbol in the active layout

Use layout_dependent = true when a shortcut should follow your active keyboard language:

sweets.bind("MOD+Cyrillic_ef", "spawn", { "foot" }, { layout_dependent = true })

This shortcut works with the Cyrillic ф key (English A position) in a Russian layout. Without this option, Sweets uses a Latin symbol from another configured layout when needed, so your usual shortcuts remain available.

Multi-step sequences

Vim-style binding:

sweets.bind("MOD+B f", "spawn", { "firefox" })
sweets.bind("MOD+B c", "spawn", { "chromium" })

Press MOD+B, release, then press f. You have one second for each step.

A key can't be both a binding and the start of a sequence. Unbind the short one first:

sweets.unbind("MOD+Q")
sweets.bind("MOD+Q Q", "close")

Options

Options go last, or in place of the argument when the action takes none.

sweets.bind("XF86AudioRaiseVolume", "spawn", {
    "wpctl", "set-volume", "@DEFAULT_AUDIO_SINK@", "5%+",
}, { repeating = true })

sweets.bind("MOD+D", "spawn", { "fuzzel" }, { description = "Launcher" })
sweets.bind("Super_L", "spawn", { "fuzzel" }, { on = "release" })
OptionDefaultEffect
repeatingfalseRepeat while the key is held
on"press""release" runs it when you tap and release the key alone
holdnoneChoose a different action after holding the key; see below
cooldown0Minimum milliseconds between runs, up to 5000
descriptionnoneLabel in the bindings list
show_in_overlaytruefalse hides the row while keeping the binding active
layout_dependentfalseMatch the base symbol in the active keyboard layout
allow_extra_modifiersfalseStill match when other modifiers are held
allow_when_lockedfalseWork on the lock screen
allow_inhibitingtruefalse keeps the key when a game grabs shortcuts
all_modesfalseStay active in binding modes
spawnnoneLaunch on an empty workspace or special_toggle, or when focus_window finds no match
monitorselected monitorChoose a connector, a monitor description, or "all" for monitor_power

Write repeating, not repeat. repeat is a Lua keyword, so { repeat = true } is a syntax error.

Short press and hold

Run one action on a short release and another when you hold the key:

sweets.bind("F10", "spawn", { "playerctl", "play-pause" }, {
    hold = { after = 500, action = "spawn", argument = { "playerctl", "next" } },
})

Tap F10 for play/pause. Hold it for half a second to skip once. Releasing after a hold does nothing more. The application receives neither key edge.

FieldDefaultEffect
afterrequiredHold time in milliseconds, from 1 to 5000
actionrequiredAction name, or a list of actions
argumentnoneArgument for the hold action; omit with an action list

Use one key with optional modifiers. Hold bindings can't use a sequence, repeating, on = "release", allow_when_locked, or a mouse action. A cooldown applies to both actions.

Several actions at once

Pass a list of up to eight actions:

sweets.bind("MOD+Alt+F", {
    { "toggle_floating" },
    { "center_window" },
}, { description = "Float and center" })

They run in order. quit and mode must come last. move_window and resize_window can't be used here.

Actions

Programs and windows

ActionArgumentResult
launch_terminal—Open an installed terminal automatically
spawncommand tableLaunch a program
close—Close the focused window
force_close—Kill the focused app
quit—, "now", or "close_windows"Confirm and quit, quit immediately, or wait for applications to close
reload—Reload the config
dismiss_error—Hide the config error bar
show_bindings—List your bindings
hide_cursor, show_cursor—Hide or show the cursor
noop—Swallow the key and do nothing
modemode nameEnter a binding mode, or "default" to leave
toggle_shortcuts_inhibit—Let the focused window grab shortcuts, or stop it
toggle_inputinput selectorTurn a device off or on
keyboard_layoutnext, prev, or 1–4Switch keyboard layout
toggle_floating—Float or tile the window
toggle_all_floating—Float every window on the workspace, or tile them all
toggle_open_as_floating—Toggle the opening preference for new windows on the current numbered workspace
raise_floating, lower_floating—Bring a floating window to the front or back
toggle_above, toggle_below—Keep the window above or below others until reload
toggle_opacity—Make the window fully opaque until pressed again
toggle_overview—Show or hide the live workspace grid
toggle_debug_damage—Toggle the red redraw overlay
toggle_gaming_mode—Turn off shadows, blur, transparency, and animations
toggle_pin—Show a floating window on every workspace
monitor_poweron, off, or toggleTurn monitors on or off temporarily
toggle_fullscreen—Fullscreen
toggle_windowed_fullscreen—Fullscreen inside the window's own slot
toggle_maximize—Maximize
minimize—Hide the window
restore_minimized—Bring back the last hidden window
set_floating_geometry{ width?, height?, position? }Set floating content size and position; see floating presets
center_window—Center a floating window or the focused scrolling column
move_floating_left/right/up/down"edge" (optional)Nudge a floating window, or move to the next edge
grow_floating_left/right/up/down"edge"Grow one side to the next edge
resize_floating_grow, resize_floating_shrink—Resize a floating window horizontally
resize_floating_grow_vertical, resize_floating_shrink_vertical—Resize a floating window vertically
scratchpad_togglenameShow, focus or hide a named tool
scratchpad_show, scratchpad_hidenameEnsure a named tool is shown or hidden
scratchpad_releasenameDetach a tool as an ordinary floating window
special_togglename (optional)Show or hide a special workspace
special_movename (optional)Move the window to a special workspace
special_next, special_prevname (optional)Cycle window families in a special workspace
special_allname (optional)Show every window in the special workspace

toggle_windowed_fullscreen tells the app it is fullscreen but keeps it in its tile. It's handy for sharing a presentation next to your notes. Some apps ignore it, and X11 apps aren't supported.

Choose a terminal

The default MOD+Return runs launch_terminal. It uses xdg-terminal-exec preferences when available, then checks installed terminals in this order:

foot, kitty, alacritty, ghostty, wezterm, rio, konsole, kgx, gnome-terminal, xfce4-terminal, tilix.

With XWayland running, xterm, uxterm, urxvt, and st are also checked. If no terminal is found, Sweets shows an error bar.

Add favorite terminal in your personal configuration (recommend):

sweets.bind("MOD+Return", "spawn", { "kitty" })

Focus or launch an app

sweets.bind("MOD+Alt+B", "focus_window", { app_id = "firefox" }, {
    spawn = { "firefox" }, cooldown = 1000,
})

Focus an open match on any workspace or monitor, restoring minimized windows. Press again to cycle through matches, starting with the most recently used. If none matches, spawn launches the app. Omit it to focus existing windows only.

Use app_id, instance, title, backend, sandbox_engine, sandbox_app_id, and exclude with window-rule matchers. Titles, app IDs and X11 instances match their current values. Use cooldown to limit launches while an app starts.

Focus and workspaces

ActionArgumentResult
focus_left/right/up/down—Focus in a direction
focus_next, focus_prev—Cycle focus in layout order
focus_last—Go back to the previous window; press again to return
focus_urgent—Focus the window asking for attention
focus_windowmatcher tableFocus an app, or launch it
focus_or_workspace_left/right/up/down—Focus in a direction, or switch workspace at the edge
recent_next, recent_previousscope (optional)Alt+Tab switcher
close_recent_selection—Close the highlighted window in the open switcher
move_left/right/up/down—Move the window in a direction
focus_output_left/right/up/down—Focus the next monitor in a direction
focus_output_next, focus_output_prev—Cycle through monitors
focus_outputmonitorFocus a named monitor
move_output_left/right/up/down—Move the window to another monitor
move_output_next, move_output_prev—Move the window to the next monitor
move_outputmonitorMove the window to a named monitor
move_output_keep_number_left/right/up/down, _next, _prev—per_monitor mode: move to the same workspace number on another monitor
workspace_swap_output_left/right/up/down, _next, _prev—Swap workspaces with another monitor
workspace1–10Switch workspace
workspace_move1–10Move the window to a workspace
workspace_move_column1–10Move the whole scrolling column to a workspace
workspace_previous—Go back to the last workspace on this monitor
workspace_relative_next, workspace_relative_prev—Next or previous workspace
workspace_move_relative_next, workspace_move_relative_prev—Move the window to the next or previous workspace
workspace_empty—Switch to the first empty workspace
workspace_move_empty—Move the window to the first empty workspace

To choose whether a move binding switches to the destination, see Follow a moved window.

Directional focus and moves cross to the next monitor at the edge. Turn that off with focus_cross_monitor and move_cross_monitor in General.

On three or more monitors, _next and _prev are easier than directions.

Focus a named monitor

Use a connector name, or the make, model, and serial shown by sweets msg outputs:

sweets.bind("MOD+F8", "focus_output", "DP-1")
sweets.bind("MOD+F9", "focus_output", { make = "DEL", serial = "ABC123" })

move_output takes the same argument and sends the focused window there:

sweets.bind("MOD+Shift+F9", "move_output", { make = "DEL", serial = "ABC123" })

Layout and resizing

ActionArgumentResult
layoutlayout nametile, monocle, centered, grid, columns, deck, dwindle, or scrolling
cycle_layout, cycle_layout_reverse—Next or previous layout
reset_layout, reset_all_layouts—Reset sizes and gaps
resize_grow, resize_shrink—Resize horizontally
resize_grow_vertical, resize_shrink_vertical—Resize vertically
gaps_grow, gaps_shrinkinner or outer (optional)Change gaps on this workspace
toggle_gaps—Hide or show gaps
cycle_master_position, cycle_master_position_reverse—Move the master area to another side
swap_with_master—Swap the window with the master; press again to swap back
focus_master—Focus the master; press again to go back
add_master, remove_master—More or fewer windows in the master area
rotate_next, rotate_prev—Rotate all windows by one slot
move_next, move_prev—Swap the window with its neighbor
consume_or_expel_left, consume_or_expel_right—Scrolling: join a column, or leave one
move_column_left, move_column_right—Scrolling: move the column
move_column_first, move_column_last—Scrolling: move the column to either end
move_column_toPositive integerScrolling: move the column to a one-based position
focus_column_first, focus_column_last—Scrolling: focus the first or last column
focus_columnPositive integerScrolling: focus the column at a one-based position
center_visible_columns—Scrolling: center the fully visible columns as a group
strip_step"next" or "prev"Pan the scrolling strip while keeping focus
cycle_column_width, cycle_column_width_reverse—Scrolling: change column width
cycle_member_size, cycle_member_size_reverse—Scrolling: cycle window height, or width in vertical strips
reset_member_size—Scrolling: reset the focused window’s size
toggle_full_width—Scrolling: make the column full width
expand_column—Scrolling: fill the free space

See Layout for how each layout resizes.

Spawning programs

spawn takes the program and each argument as separate strings:

sweets.bind("MOD+E", "spawn", { "foot", "nvim", "/tmp/notes.txt" })

There is no shell. Pipes, $VARS, *, and ~ don't work. For those, run a shell yourself:

sweets.bind("Print", "spawn", { "sh", "-c", "grim - | wl-copy" })

For screenshots without helper tools, see sweetshot.

Program errors go to the session log.

Open one window differently

Use a named command to launch one floating window without a permanent window rule:

sweets.bind("MOD+Alt+Return", "spawn", {
    command = { "foot" },
    floating = true,
    size = { 900, 600 },
    position = "center",
})
FieldDefaultEffect
commandrequiredProgram and arguments, as separate strings
floatingwindow rulesChoose floating or tiled for this launch
sizewindow rulesContent width and height; fractions use the available screen area
positionwindow rulesA window-rule position

Size or position makes the window floating. To request tiling, remove both fields and keep only the command and floating = false:

sweets.bind("MOD+Alt+Return", "spawn", {
    command = { "foot" },
    floating = false,
})

Window size limits, destination rules, pinning and fullscreen still apply.

This works with Wayland apps that return the launch token before opening, such as foot and GTK 4 apps. Apps that ignore it keep their usual behavior. An existing window is never changed. XWayland apps are not supported here.

The override also works with spawn_origin_placement = false.

Replacing and removing bindings

Bind the same keys again to replace a default:

sweets.bind("MOD+Return", "spawn", { "alacritty" })

Remove one with sweets.unbind:

sweets.unbind("MOD+Space")

To block a key from reaching apps, bind it to noop:

sweets.bind("F7", "noop")

A bad binding rejects the whole config, and the previous bindings stay active.

Running a binding while locked

Bindings don't run on the lock screen. To allow one, add allow_when_locked:

sweets.bind("XF86AudioMute", "spawn", {
    "wpctl", "set-mute", "@DEFAULT_AUDIO_SINK@", "toggle",
}, { allow_when_locked = true })

It works only with a single-key spawn.

Anyone at your keyboard can run that program while the screen is locked.

Shortcut inhibition

Games, virtual machines, and remote desktops can grab your shortcuts while focused. Keep a key with Sweets anyway:

sweets.bind("MOD+1", "workspace", 1, { allow_inhibiting = false })

Press MOD+Escape to take your shortcuts back.

Force close

force_close ends an app that won't close. All its windows close too.

sweets.bind("MOD+Ctrl+Q", "force_close")

A window that ignores close for five seconds gets the border.unresponsive color. X11 apps aren't supported.

Default bindings

These always work, even without a config:

KeysAction
MOD+ReturnOpen an installed terminal
MOD+QClose the window
MOD+Shift+QQuit (press twice)
MOD+Shift+RReload the config
MOD+Shift+EHide the config error bar
MOD+EscapeToggle shortcut inhibition
MOD+Shift+slashList your bindings
MOD+SpaceFloat or tile
MOD+FFullscreen
MOD+J, MOD+KFocus next or previous
MOD+Shift+H/J/K/LMove the window
MOD+equal, MOD+minusResize horizontally
MOD+Shift+equal, MOD+Shift+minusResize vertically

The installed config adds:

KeysAction
MOD+H/L, MOD+ArrowsFocus in a direction
MOD+Shift+ArrowsMove the window
MOD+1..9/0Switch to workspace 1–10
MOD+Shift+1..9/0Move the window to workspace 1–10
MOD+Ctrl+H/J/K/L, MOD+Ctrl+ArrowsFocus another monitor
MOD+Ctrl+Shift+H/J/K/L, MOD+Ctrl+Shift+ArrowsMove the window to another monitor
MOD+Shift+FMaximize
MOD+M, MOD+Shift+MMinimize, restore
MOD+S, MOD+Shift+SShow special workspace, move window there
MOD+W, MOD+Shift+WNext or previous layout
MOD+I, MOD+Shift+IMove the master area
MOD+U, MOD+Shift+UReset this layout, or all layouts
MOD+KP_Add, MOD+KP_SubtractResize horizontally
MOD+Shift+KP_Add, MOD+Shift+KP_SubtractResize vertically

Media keys

KeysActionNeeds
XF86AudioRaiseVolume, XF86AudioLowerVolumeVolume ±5%wpctl
XF86AudioMute, XF86AudioMicMuteMute output or micwpctl
XF86MonBrightnessUp, XF86MonBrightnessDownBrightness ±5%brightnessctl
XF86AudioPlay, XF86AudioPausePlay / pauseplayerctl
XF86AudioNext, XF86AudioPrev, XF86AudioStopNext, previous, stopplayerctl
XF86TouchpadToggleTurn the touchpad off or on—

Media keys also work on the lock screen. Sweets doesn't install the tools. On PulseAudio, use the pactl lines from the installed sweets.lua.

If one brightness press jumps twice, your laptop sends the key from two devices. Check with libinput debug-events.

To use the power key, set general.power_key = "compositor" first. Otherwise the system powers off on its own.

Listing your bindings

MOD+Shift+slash shows your active bindings. Any key, click, or scroll closes it. Bindings with a description are listed first.

Hide a row without disabling its shortcut:

sweets.bind("MOD+Ctrl+F12", "layout", "tile", { show_in_overlay = false })

This option also works for mouse and scroll bindings, including bindings in named modes. sweets msg binds still lists hidden bindings.

Change its look with sweets.bindings_overlay:

sweets.bindings_overlay({
    columns = 2,
    background = "#1C1F26F2",
    text = "#E6E9F0",
    accent = "#7AA2F7",
    font = "Monospace 10",
})
FieldDefaultEffect
columns21–4 columns
background"#1C1F26F2"Panel color
text"#E6E9F0"Label color
accent"#7AA2F7"Title and key color
font"Monospace 10"Font

To print all bindings in a terminal, run sweets msg binds.

On this page