Sweets

Monitors

Resolution, refresh rate, scale, position, rotation, and VRR

sweets.monitor configures a monitor. Without a rule, a monitor uses its preferred mode and an automatic scale, placed left to right.

sweets.monitor("DP-1", {
  mode = { 2560, 1440 },
  refresh_hz = 144,
  scale = 1.5,
  position = { 0, 0 },
})

sweets.monitor("eDP-1", { enabled = false })

Finding your monitors

sweets msg outputs

This lists each monitor's name, make, model, serial, and available modes.

Naming a monitor

RuleExampleMatches
Connector"DP-1", "HDMI-A-1", "eDP-1"Whatever is plugged into that port
Description{ make = "DEL", model = "S2719DGF" }That monitor, on any port
Fallback"*"Every monitor without its own rule
sweets.monitor({ make = "DEL", model = "S2719DGF" }, { scale = 1.5 })
sweets.monitor("*", { mode = "highest_refresh" })

Copy make, model, and serial from sweets msg outputs. They aren't the names on the box: Dell is DEL, LG is GSM. To tell two identical monitors apart, add serial.

The fallback can't set position, enabled, or focus_at_startup.

XWayland primary output

Choose the primary monitor for X11 apps:

sweets.xwayland({
  enabled = true,
  primary_output = "DP-2",
})

Use a connector or monitor description. Add serial to distinguish identical monitors.

primary_output reloads live. Set false to clear the preference. Missing or disabled monitors fall back to the selected output until they return. Some X11 apps ignore this setting. Changing enabled requires restarting Sweets.

Options

FieldDefaultEffect
mode"preferred"{ width, height }, "preferred", "highest", or "highest_refresh"
refresh_hzbest for the modeRefresh rate. Needs a { width, height } mode
scale"auto"Scale, like 1.5, or "auto"
positionautomaticPosition, { x, y }
transform"normal"Rotation: "90", "180", "270", or "flipped", "flipped-90", …
enabledtruefalse turns the monitor off
max_render_timeoffNative render budget in integer milliseconds; see Render deadline
adaptive_syncfalseVRR: true, false, or "on_demand"
rgb_range"auto"Color range: "auto", "full", or "limited"
hdrfalseHDR: true turns on the monitor's HDR mode
sdr_brightness203How bright white is with hdr on, 50 to 1000
backgroundgeneral.backgroundComplete background paint for this monitor
focus_at_startupfalseStart the session on this monitor
gaps, border, window, strutsglobal valuesPer-monitor look
scrollingsweets.scrollingScrolling defaults for this monitor

Your rule for a monitor replaces the installed rule for it completely. Copy any installed fields you want to keep.

Render deadline

sweets.monitor("DP-1", { max_render_time = 6 })

Delays rendering to include later input. Start with 6 ms and check sweets msg frame DP-1. If render_deadline_misses rises, increase the budget or remove it for immediate rendering.

Accepts 1–1000 ms within the refresh interval. Ignored in nested and headless sessions, or while adaptive sync is active.

Scale

sweets.monitor("eDP-1", { scale = 1.5 })

Use steps like 1.25, 1.5, or 2. With "auto", Sweets picks a scale from the monitor's size, like GNOME does. If you'd rather have a different number, write it.

Position

Positions are in scaled pixels. A 4K monitor at scale 1.5 is 2560 wide, so the next one starts at 2560:

sweets.monitor("DP-1", { position = { 0, 0 }, mode = { 3840, 2160 }, scale = 1.5 })
sweets.monitor("DP-2", { position = { 2560, 0 }, mode = { 2560, 1440 }, scale = 1 })

Monitors can't overlap. If they do, the error shows each monitor's size so you can fix the numbers.

With scale = "auto", check the size in sweets msg outputs before writing positions. Or leave position out and let Sweets place them.

Turning a monitor off

enabled = false turns it off in your config. Its windows move to other monitors.

Use monitor_power to turn a screen off temporarily. Its windows stay in place.

sweets.bind("MOD+Ctrl+P", "monitor_power", "toggle")
sweets.bind("MOD+F12", "monitor_power", "toggle", { monitor = "all" })
sweets.bind("MOD+Shift+F12", "monitor_power", "toggle", { monitor = "DP-2" })

Omit monitor to use the selected monitor. You can also use a connector name, a monitor description, or "all". With "all", toggle turns every enabled monitor off if any is on, and turns them all on otherwise.

Or from a terminal:

sweets msg output-power DP-1 off

Gaps, borders, and struts

sweets.monitor("eDP-1", {
  gaps = { inner = 4, outer = 4 },
  border = { width = 1 },
  window = { corner_radius = 6 },
  struts = { top = 0 },
})

These take the same fields as sweets.layout_style. A workspace rule wins over them.

Adaptive sync (VRR)

"on_demand" turns on VRR only for fullscreen apps you choose:

sweets.monitor("DP-1", { adaptive_sync = "on_demand" })
sweets.window_rule({ app_id = "steam", adaptive_sync = true })

true keeps VRR on all the time, which makes some monitors flicker on the desktop. The monitor must support VRR.

RGB range

If colors look wrong on one monitor:

SymptomTry
Blacks too dark, too much contrastrgb_range = "limited"
Washed out, gray blacksrgb_range = "full"
sweets.monitor("DP-1", { rgb_range = "full" })

Check the monitor's own "Black level" setting first. This option needs driver support, such as Intel's.

HDR (experimental)

sweets.monitor("DP-1", { hdr = true })

The monitor switches to HDR. The desktop looks the same and HDR apps like mpv and games show HDR. Restart apps that were open before you turned it on

  • The monitor must support HDR10. Look for hdr_supported: true in sweets msg outputs
  • Desktop too dim or too bright? Change sdr_brightness
  • Night-light tools like gammastep don't tint an HDR monitor
  • If colors look cooler or bluer, that comes from the monitor, not Sweets
  • Screenshots and screen sharing clip the brightest parts of HDR video to white

Changing monitors on the fly

Rotate a monitor temporarily through IPC:

sweets msg output-transform DP-2 rotate90

Find its ID and original transform with sweets msg outputs. Use the original transform to restore it afterward. A config reload puts your monitor rules back.

Tools like wlr-randr and kanshi also work with Sweets. Their changes are temporary too.

On this page