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| Modifier | Meaning |
|---|---|
MOD | Your mod_key |
Ctrl, Shift, Alt | As named |
Super | Logo / Windows key |
AltGr | XKB level 3 |
ISO_Level5_Shift | XKB level 5 |
- Key names are XKB keysyms:
q,Return,space,equal,XF86AudioRaiseVolume. Names are case-insensitive. qandQare the same key. AddShiftif you mean Shift.code:Nmatches a physical key whatever your layout. FindNwithwev.- 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" })| Option | Default | Effect |
|---|---|---|
repeating | false | Repeat while the key is held |
on | "press" | "release" runs it when you tap and release the key alone |
hold | none | Choose a different action after holding the key; see below |
cooldown | 0 | Minimum milliseconds between runs, up to 5000 |
description | none | Label in the bindings list |
show_in_overlay | true | false hides the row while keeping the binding active |
layout_dependent | false | Match the base symbol in the active keyboard layout |
allow_extra_modifiers | false | Still match when other modifiers are held |
allow_when_locked | false | Work on the lock screen |
allow_inhibiting | true | false keeps the key when a game grabs shortcuts |
all_modes | false | Stay active in binding modes |
spawn | none | Launch on an empty workspace or special_toggle, or when focus_window finds no match |
monitor | selected monitor | Choose 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.
| Field | Default | Effect |
|---|---|---|
after | required | Hold time in milliseconds, from 1 to 5000 |
action | required | Action name, or a list of actions |
argument | none | Argument 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
| Action | Argument | Result |
|---|---|---|
launch_terminal | — | Open an installed terminal automatically |
spawn | command table | Launch 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 |
mode | mode name | Enter a binding mode, or "default" to leave |
toggle_shortcuts_inhibit | — | Let the focused window grab shortcuts, or stop it |
toggle_input | input selector | Turn a device off or on |
keyboard_layout | next, prev, or 1–4 | Switch 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_power | on, off, or toggle | Turn 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_toggle | name | Show, focus or hide a named tool |
scratchpad_show, scratchpad_hide | name | Ensure a named tool is shown or hidden |
scratchpad_release | name | Detach a tool as an ordinary floating window |
special_toggle | name (optional) | Show or hide a special workspace |
special_move | name (optional) | Move the window to a special workspace |
special_next, special_prev | name (optional) | Cycle window families in a special workspace |
special_all | name (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
| Action | Argument | Result |
|---|---|---|
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_window | matcher table | Focus 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_previous | scope (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_output | monitor | Focus 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_output | monitor | Move 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 |
workspace | 1–10 | Switch workspace |
workspace_move | 1–10 | Move the window to a workspace |
workspace_move_column | 1–10 | Move 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
| Action | Argument | Result |
|---|---|---|
layout | layout name | tile, 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_shrink | inner 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_to | Positive integer | Scrolling: move the column to a one-based position |
focus_column_first, focus_column_last | — | Scrolling: focus the first or last column |
focus_column | Positive integer | Scrolling: 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",
})| Field | Default | Effect |
|---|---|---|
command | required | Program and arguments, as separate strings |
floating | window rules | Choose floating or tiled for this launch |
size | window rules | Content width and height; fractions use the available screen area |
position | window rules | A 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:
| Keys | Action |
|---|---|
MOD+Return | Open an installed terminal |
MOD+Q | Close the window |
MOD+Shift+Q | Quit (press twice) |
MOD+Shift+R | Reload the config |
MOD+Shift+E | Hide the config error bar |
MOD+Escape | Toggle shortcut inhibition |
MOD+Shift+slash | List your bindings |
MOD+Space | Float or tile |
MOD+F | Fullscreen |
MOD+J, MOD+K | Focus next or previous |
MOD+Shift+H/J/K/L | Move the window |
MOD+equal, MOD+minus | Resize horizontally |
MOD+Shift+equal, MOD+Shift+minus | Resize vertically |
The installed config adds:
| Keys | Action |
|---|---|
MOD+H/L, MOD+Arrows | Focus in a direction |
MOD+Shift+Arrows | Move the window |
MOD+1..9/0 | Switch to workspace 1–10 |
MOD+Shift+1..9/0 | Move the window to workspace 1–10 |
MOD+Ctrl+H/J/K/L, MOD+Ctrl+Arrows | Focus another monitor |
MOD+Ctrl+Shift+H/J/K/L, MOD+Ctrl+Shift+Arrows | Move the window to another monitor |
MOD+Shift+F | Maximize |
MOD+M, MOD+Shift+M | Minimize, restore |
MOD+S, MOD+Shift+S | Show special workspace, move window there |
MOD+W, MOD+Shift+W | Next or previous layout |
MOD+I, MOD+Shift+I | Move the master area |
MOD+U, MOD+Shift+U | Reset this layout, or all layouts |
MOD+KP_Add, MOD+KP_Subtract | Resize horizontally |
MOD+Shift+KP_Add, MOD+Shift+KP_Subtract | Resize vertically |
Media keys
| Keys | Action | Needs |
|---|---|---|
XF86AudioRaiseVolume, XF86AudioLowerVolume | Volume ±5% | wpctl |
XF86AudioMute, XF86AudioMicMute | Mute output or mic | wpctl |
XF86MonBrightnessUp, XF86MonBrightnessDown | Brightness ±5% | brightnessctl |
XF86AudioPlay, XF86AudioPause | Play / pause | playerctl |
XF86AudioNext, XF86AudioPrev, XF86AudioStop | Next, previous, stop | playerctl |
XF86TouchpadToggle | Turn 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",
})| Field | Default | Effect |
|---|---|---|
columns | 2 | 1–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.