Sweets

Binding Modes

Switch to a separate set of bindings, like a resize mode

A binding mode is a separate set of bindings. While it's active, your normal bindings pause.

sweets.mode("resize", function()
  sweets.bind("Left", "resize_shrink")
  sweets.bind("Right", "resize_grow")
  sweets.bind_scroll("ScrollUp", "resize_grow")
  sweets.bind_scroll("ScrollDown", "resize_shrink")
  sweets.bind("Escape", "mode", "default")
end)

sweets.bind("MOD+R", "mode", "resize")

Press MOD+R, then the arrow keys resize the window. Escape takes you back.

  • "default" means your normal bindings.
  • Every mode needs a binding back to "default".
  • Modes can't open other modes.
  • Names use letters, digits, _, and -. You can have up to 16 modes.

Enter from a terminal

sweets msg set-binding-mode resize
sweets msg set-binding-mode default

The name must match a mode in your config exactly. Selecting the active mode does nothing.

Unbound keys

Unbound keys normally reach the app. To leave a launcher mode on a typo, add a trailing options table:

sweets.mode("launch", function()
  sweets.bind("T", { { "spawn", { "foot" } }, { "mode", "default" } })
  sweets.bind("Escape", "mode", "default")
end, { unmatched = "exit" })

sweets.bind("MOD+Alt+R", "mode", "launch")
unmatched valueUnbound keyMode
"forward" (default)Sent to the appStays active
"consume"SwallowedStays active
"exit"SwallowedReturns to normal bindings

Modifier keys don't trigger this setting. It pauses while an app grabs your shortcuts. Known bindings still run, and every mode still needs an exit binding.

Keys that work in every mode

Add all_modes = true to a normal binding to keep it active inside modes. The installed volume, brightness, and media keys do this.

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

A mode can override or sweets.unbind that key for itself.

Getting unstuck

These always work inside a mode:

Keys or commandResult
MOD+Shift+RReload the config and leave the mode
MOD+Shift+slashShow the mode's bindings
MOD+Shift+QQuit Sweets
sweets msg reset-binding-modeLeave the mode from a terminal

Locking the screen also leaves the mode.

Mode indicator

A small label shows the active mode on every monitor. Style it with sweets.mode_indicator:

sweets.mode_indicator({
  position = "top_center",
  margin = 16,
  background = "#1C1F26E6",
  text = "#FFFFFF",
  accent = "#7AA2F7",
  font = "Monospace 10",
})
FieldDefaultEffect
enabledtrueShow the label
positiontop_centertop_left, top_center, top_right, bottom_left, bottom_center, or bottom_right
margin12Distance from the edge, 0–512
background#1C1F26E6Background color
text#FFFFFFText color
accent#7AA2F7Left stripe color
fontMonospace 10Font

With enabled = false, nothing shows that a mode is active. Make sure you remember how to leave it.

Show the mode in a bar

sweets msg status includes a binding_mode field while a mode is active.

On this page