Snapping

The model

A layout is a set of zones, each a rectangle expressed as a fraction of the screen so the same layout fits any monitor. A screen has one active layout at a time. Drag a window and hold the activation trigger, and the zones of that layout are drawn over the screen. The one under your cursor highlights, and releasing the window fits it to that zone.

Snapping is assigned per screen, per virtual desktop, and per activity, so one monitor can snap while another tiles. Meta+Shift+T cycles the focused screen through the modes you have enabled, and Snapping.Enabled takes the mode out of that rotation entirely.

A window that is snapped is not trapped. Dragging it out restores the size it had before, keyboard shortcuts move it between zones, and Meta+F floats it above the placed windows.

Activation

What summons the overlay is a trigger list, Snapping.Behavior.Triggers, rather than a single modifier. Each entry pairs a modifier with an optional mouse button, and any entry matching brings the zones up. That lets you keep Alt as the habit and add a thumb button for the times your other hand is busy.

The default is one entry, Alt with no mouse button. In config.json that reads:

"Triggers": [ { "modifier": 3, "mouseButton": 0 } ]

The modifier field is not a Qt modifier bitmask, which is the natural assumption and the wrong one. It is a small enumeration:

mouseButton is a Qt button bit, and 0 means no button is required. The left button is not on the list because it is the one already dragging the window.

Two settings change the shape of the gesture rather than what starts it. ToggleActivation makes the trigger a tap to turn the overlay on and a second tap to turn it off, instead of something held. ReleaseGraceMs keeps the overlay alive briefly after the trigger lifts, which matters more than it sounds: with a mouse-button trigger, the same hand releases the button and drops the window, and the button usually lifts a few milliseconds first. Without the grace period that drop would miss.

Setting the modifier to Always active (8) makes every drag show the zones with nothing held. It is the same switch as "Activate on every drag" in the settings app, and it is a modifier value rather than a separate toggle.

Snap assist

After a window lands in a zone, the empty zones can offer thumbnails of your other windows so the rest of the layout fills with a click each. Three settings under Snapping.Behavior.SnapAssist control it, and they stack:

• FeatureEnabled The master switch. Off, no snap assist happens by any route.
• Enabled Show the picker after every snap, without waiting for you to hold anything.
• Triggers Hold this while releasing a window to get the picker for that one snap. The default is the middle mouse button (mouseButton: 4) with no modifier. This is the way in when the always-show toggle is off.

Zone span

A window does not have to take exactly one zone. Holding the span trigger while dragging paints across adjacent zones, and the window is fitted to their combined rectangle on release, so a three-column layout also gives you every two-column pairing without another layout.

The span trigger works like the activation trigger, with its own list, toggle mode, and grace period. There is one wrinkle worth knowing before you hand-edit anything. Snapping.Behavior.ZoneSpan exposes both a Modifier and a Triggers list that hold the same thing. Triggers is the real setting. Modifier is a single-modifier view kept for compatibility. Writing it syncs the value into the first trigger entry, and a config with no stored trigger list has its list synthesized from it. Set one or the other, not both.

The span keyboard shortcuts are a different mechanism from the drag modifier. Ctrl+Alt with an arrow key extends the focused window across the neighbouring zone, and once the span reaches the edge of the layout the same key starts pulling the opposite edge in.

Overlay appearance

The overlay is drawn by a shader, so the zone colours, opacity, borders, and labels are all yours to set. Colours live under Snapping.Zones.Colors. Leaving one empty is not a missing value. It means the zone follows your Plasma colour scheme, which is why they ship empty.

• Snapping.Zones.Opacity Separate values for the zone under the cursor and the rest.
• Snapping.Zones.Border Width and corner radius. The radius rounds the zone's shape and applies at zero border width too.
• Snapping.Zones.Labels Typeface, weight, scale, and colour for the number drawn in each zone.
• Snapping.Effects Zone numbers, the flash on layout switch, and which on-screen displays appear. OverlayDisplayMode switches between drawing zone rectangles and showing a preview of the whole layout.

For the shader itself rather than its colours, the overlay shader gallery has the 27 packs that ship in-box and the parameters each exposes.

What happens to windows

Snapping.Behavior.WindowHandling is the group that decides what snapping does to a window over its life, and it is where most surprises get resolved.

• RestoreOnUnsnap Give a window its old size back when it is dragged out of a zone. On by default.
• KeepOnResolutionChange Put windows back in their zones after the screen resolution changes, which is what you want when a monitor wakes or a game exits.
• RestoreOnLogin Return an app to the zone it was last snapped in when it reopens, during the session or after a logout.
• MoveNewToLastZone Snap every newly opened window into whichever zone you snapped into most recently. Off by default.
• KeepFloatingAbove Keep floated windows stacked over the snapped ones. A window rule that sets a layer wins for the windows it matches.
• UnfloatFallbackToZone When you unfloat a window that was never snapped, send it to a zone rather than leaving it loose. It tries the last used zone, then the first empty one, then the first zone.
• StickyWindowHandling What to do with windows shown on every desktop: treat them normally, only restore them, or ignore them entirely.

Windows you never want touched are better handled globally than per mode. Exclusions holds a minimum width and height, plus a toggle for transient windows such as dialogs, popups, and toolbars. It applies to every placement mode at once.

The edge picker

Dragging a window to a screen edge can open a picker of layouts, so switching the whole screen's layout is part of the same drag that places the window. Snapping.ZoneSelector.TriggerDistance is how close to the edge you have to come, and Position puts the picker anywhere in a three-by-three grid on the screen.

Preview size is automatic unless SizeMode is set to manual. With PreviewLockAspect on, the height follows the width using the screen's own aspect ratio, so the previews are shaped like the screen they represent.

Next

• Layout gallery → Every zone layout that ships in-box, drawn from the same JSON the daemon loads.
• Settings reference → Every key named on this page, with its type, default, and accepted values.
• Keyboard shortcuts → Snapping to a zone by number, moving between zones, and spanning by keyboard.
• From FancyZones → The feature map if snapping is the mode you came here for.