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 outputsThis lists each monitor's name, make, model, serial, and available modes.
Naming a monitor
| Rule | Example | Matches |
|---|---|---|
| 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
| Field | Default | Effect |
|---|---|---|
mode | "preferred" | { width, height }, "preferred", "highest", or "highest_refresh" |
refresh_hz | best for the mode | Refresh rate. Needs a { width, height } mode |
scale | "auto" | Scale, like 1.5, or "auto" |
position | automatic | Position, { x, y } |
transform | "normal" | Rotation: "90", "180", "270", or "flipped", "flipped-90", … |
enabled | true | false turns the monitor off |
max_render_time | off | Native render budget in integer milliseconds; see Render deadline |
adaptive_sync | false | VRR: true, false, or "on_demand" |
rgb_range | "auto" | Color range: "auto", "full", or "limited" |
hdr | false | HDR: true turns on the monitor's HDR mode |
sdr_brightness | 203 | How bright white is with hdr on, 50 to 1000 |
background | general.background | Complete background paint for this monitor |
focus_at_startup | false | Start the session on this monitor |
gaps, border, window, struts | global values | Per-monitor look |
scrolling | sweets.scrolling | Scrolling 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 offGaps, 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:
| Symptom | Try |
|---|---|
| Blacks too dark, too much contrast | rgb_range = "limited" |
| Washed out, gray blacks | rgb_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: trueinsweets msg outputs - Desktop too dim or too bright? Change
sdr_brightness - Night-light tools like
gammastepdon'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 rotate90Find 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.