Sway School

Introduction

Sway is a tiling Wayland compositor. The default reaction to it is "I don't get how layouts work." This tutorial fixes that — not by listing keys, but by teaching you the tree model sway uses internally. Once you see the tree, every keystroke becomes obvious.

The lessons build on each other. Each one ends with a quiz that lets you check your understanding before moving on. Don't skip the quizzes — they're how you find out whether the model actually clicked.

The keys you'll use most

The full list is in the cheat sheet at the bottom.

L1A window is just a rectangle

Open one terminal: $mod+t. It fills the screen, minus a small gap.

One window takes all the space available to it.

That's the whole lesson. No tree, no containers — just one window filling its space.

L2A second window has to share the space

Open another terminal. Sway picks a direction (default: side-by-side) and shrinks the existing window to make room.

Sway never overlaps tiled windows. Space is always divided, never stacked.

This is the foundational difference between a tiling WM and a traditional one. There's no z-order to fight with for tiled windows.

L3Sway remembers the arrangement

Sway didn't happen to put your three windows in a row. It decided "these go horizontally" and remembers that decision. Open a fourth terminal — it joins the row, four side-by-side.

Sway is keeping a note: "these windows are arranged horizontally." That note will eventually have a name: container (L8).

For now, just hold the idea: arrangements are remembered, not coincidental.

L4Focus: sway always knows which window is active

One window has a coloured border (blue in the Catppuccin theme). That's the focused window — the one keystrokes go to.

Move focus with either of these — they're bound identically:

• $mod+h / j / k / l (vim-style: left/down/up/right)
• $mod+← / ↓ / ↑ / → (arrow keys, exactly the same)

This config has focus_wrapping no, so focus stops at the edge. Press $mod+h (or $mod+←) on the leftmost window and nothing happens — you're already as far left as you can go.

L5New windows appear next to the focused one

The single most important rule:

A new window opens next to whichever window is currently focused, in whatever arrangement that window lives in.

Proof: with three terminals A, B, C in a row, focus the leftmost (A) and open a new terminal. The new window appears between A and B, not at the end of the row. Focus is the anchor.

L6You choose the direction before opening the next window

So far sway has been picking the direction (horizontal). Now you take the wheel.

These keys do nothing visible by themselves. They just set up the direction for the next window you open.

Recipe to build a column: focus a window → $mod+[ → $mod+t. The new terminal appears below.

L7Arrangements stick to their spot

Once you've established a direction in a slot (e.g. made a vertical column), new windows opened inside that slot keep going in that direction — without needing the bracket key again.

Proof: focus a window inside your vertical column, hit $mod+t, and the new terminal stacks into the column rather than popping out sideways.

The slot knows what it is. Sway carries the arrangement forward until you change direction again with [ or ].

This is the moment the mental model clicks for most people. Everything from here on is variations on this one idea.

L8Containers — the tree, finally named

That "slot that knows what it is" has a name: a container.

A container = a remembered arrangement, with windows (or other containers) inside it.

Containers can hold:

• Windows (the things you actually see), or
• Other containers (which themselves hold windows or more containers).

That nesting is the tree. Russian dolls of remembered arrangements.

See your tree

Run this in any terminal:

swaymsg -t get_tree | grep -E '"(name|layout)"' | head -40

Read the output as nested boxes:

Worked example

A workspace with one tile on the left and a vertical column of two tiles on the right looks like this in the dump:

"name": "4",                          ← workspace 4
  "layout": "splith",                 ← workspace is horizontal
      "layout": "none",
      "name": "π - dotfiles",         ← a window (left side)
      "layout": "splitv",             ← a vertical container (the column!)
          "layout": "none",
          "name": "Chrome",           ← window in column
          "layout": "none",
          "name": "swaymsg …",        ← window in column

As a picture:

L8.5The correct mental model for splith / splitv

This trips up almost everyone. The naming convention:

• splith = children laid out horizontally (a side-by-side row)
• splitv = children laid out vertically (a stacked column)

The name describes how the children are arranged, NOT the direction of the divider line between them.

Why it feels backwards

Most people's first instinct is to picture the divider:

• "vertical split" → a vertical line down the middle → windows side-by-side
• "horizontal split" → a horizontal line across the middle → windows stacked

That's the CSS / Photoshop / "split a board in half" intuition. It's perfectly reasonable — it's just the opposite of sway's. Sway names from the result's point of view: see a row → splith. See a column → splitv.

Cheat table

L8.75The insertion rule (the one rule to rule them all)

Everything you've learned so far is consequences of a single rule.

When you open a new window, sway:
1. Looks at the focused window
2. Finds the container that window lives in (its parent)
3. Inserts the new window into that container, right after the focused one

The new window is always a sibling of the focused window — same parent, immediately after.

The bracket-key twist

The bracket keys ($mod+[ and $mod+]) don't just "set a direction." They do something sneakier:

They ensure the focused window's parent is of the requested type, wrapping the focused window in a new container if it isn't.

So if you're focused on A inside splith [ A B C ] and hit $mod+[, sway silently rewraps A:

Now opening a new terminal places it inside the new splitv (next sibling of A):

Sway is smart: brackets are no-ops when the parent already matches

If the focused window's parent is already the requested layout, the bracket key does nothing. No new wrapping, no nested-container tower.

Hit $mod+[ ten times in a row inside a splitv — the tree is unchanged after the first one (which itself was a no-op if you were already in a splitv). This is why your tree never gets bloated from idle keypresses.

The full table

L9Focus parent / focus child

Until now, focus has always meant "a window is highlighted." But the tree has more than just windows in it — it has containers too. And sometimes you want to operate on a whole container instead of one window inside it.

What you'll see

Focus a window normally — the border wraps just that window. Press $mod+c: the border expands to wrap the entire parent container, possibly multiple windows. That's sway saying "focus is now on the container, not the window."

Press $mod+c again → expands further to the grandparent, and so on up to the workspace itself.

Press $mod+Ctrl+c to walk back down. Sway remembers which child you came from.

Why this matters

When focus is on a container, commands act on the whole container:

• Send a whole column to another workspace: focus a column container, hit $mod+Shift+3 — the entire subtree moves.
• Tab a whole group: focus a row, hit $mod+Ctrl+f — every direct child becomes a tab.
• Wrap a whole subtree in a new split: focus a row, hit $mod+[ — the entire row becomes the top child of a new splitv.
• Float a whole group: focus a container, hit $mod+Shift+space — the whole subtree floats together.

L10Mutating the tree (changing what's already there)

You can build trees (L6, L7) and read trees (L8). Now: how to change them after the fact.

Changing a container's layout (the easy mutation)

Focus any window. The window's parent container is what these commands act on:

• $mod+Ctrl+f → set parent layout to tabbed
• $mod+period → toggle parent layout between tabbed and split
• $mod+] / $mod+[ → ensure parent is splith / splitv (wrapping if needed; see L8.75)

Changing the tree shape (the powerful mutation)

Combine $mod+c from L9 with bracket keys from L8.75 to wrap whole subtrees. Recipe to add a status-bar-style window across the bottom of an existing layout:

1. Focus any window in the layout.
2. $mod+c until the border wraps the entire workspace content (everything you want above the new bar).
3. $mod+[ → wraps that whole subtree in a fresh splitv.
4. $mod+t → new terminal appears below the entire layout.

Without the $mod+c step, the bracket key would only wrap one window. $mod+c is what makes mutations apply at the right scope.

Tabs that hold containers

A subtle but mind-bending consequence of L8.75 + L10: when you tab a row that contains a column, you get tabs where one of the tabs is the entire column. Click that tab and the screen fills with the column rendered as a splitv. You can build trees of arbitrary nesting, mixing splits and tabs, for any layout you want.

L11Moving windows through the tree

You already know $mod+Shift+hjkl moves a window. Now we look at what it actually does.

$mod+Shift+<direction> walks the focused window through the tree in that direction — swapping with siblings, escaping outward, or entering inward as needed.

It's the inverse of $mod+<direction>: arrow keys read the tree, shift+arrows rewrite it.

The three cases

When you press $mod+Shift+l (move right), one of these happens:

Case A — swap with a sibling

If there's a sibling immediately to the right in the same parent, they swap places.

Case B — escape outward

If there's no sibling that way, but a parent further up has space, the window pops out of its container.

Case C — enter a sibling container

If the next sibling in that direction is itself a container, the window dives into it.

Bonus case — escape from a perpendicular layout

If you're inside a splitv and press "right," sway walks up the tree until it finds a parent that supports horizontal movement, then drops the window there.

Sway never gets stuck — it just keeps escaping until the direction makes sense.

L12Floating windows

A floating window lives outside the tree. It has no parent, no siblings, no layout. It's just a rectangle that sits on top of everything tiled.

That's the whole concept. Everything else is consequences.

Toggle and verify

• $mod+Shift+space → toggle the focused window between tiled and floating (i3/sway default).

Verify it actually floated by looking for "type": "floating_con" in the tree dump:

swaymsg -t get_tree | grep -B 1 '"type":' | grep -E '"(name|type)"'

Mouse: hold $mod and drag

• $mod + left-click drag anywhere on the window → move it
• $mod + right-click drag → resize it

Requires floating_modifier $mod normal in your config.

Two stages per workspace

$mod+hjkl only navigates within the layer you're in (tiled or floating). To cross between them:

• $mod+a → focus mode_toggle (jump between tiled tree and floating layer)
• Mouse → just hover, since focus_follows_mouse yes
• $mod+Tab → the fuzzel windows picker

Each workspace has two stages: tiled (back) and floating (front). $mod+a is the curtain between them.

Un-float placement gotcha

When you $mod+Shift+space a floater back to tiled, it's treated as a brand new window: inserted via the L8.75 rule as the next sibling of the most recently focused tile. Sway does not remember where the window came from before floating.

To control placement: $mod+a into the tree, walk to the desired neighbour, $mod+a back to the floater, then $mod+Shift+space.

Keyboard resize — use px, not ppt

Auto-floating rules

Use for_window to auto-float specific apps. Find the app_id with:

swaymsg -t get_tree | jq -r '.. | select(.type?=="con" or .type?=="floating_con") | "\(.app_id // .window_properties.class // "?")  ::  \(.name)"' | grep -i <app-name>

Then add a rule like:

for_window [app_id="^pavucontrol$"] floating enable

The "summon and dismiss" pattern

For utility popups you summon, type into, and dismiss — audio mixers, calculators, password managers — use a richer rule that floats and sets a known size and position:

for_window [app_id="^wiremix-float$"] floating enable, resize set 720 480, move position center
for_window [app_id="^org\.gnome\.Calculator$"] floating enable, resize set 480 600, move position center

Every launch: float, resize to a known size, centre on the active output. The window appears in the same predictable spot every time, with no manual cleanup.

The for_window cookbook

L13Scratchpad

Scratchpad is a hideout for floating utility windows that aren't bound to any workspace. Stash with one key, summon with another.

Bindings

The model: a flat list of floaters with no workspace

• Scratchpad windows are always floating. Stashing converts a tiled window to floating.
• They have no workspace — they appear on whichever workspace you're on when you summon.
• Each window remembers its size and position. Set once, summons always restore.
• You can stash any number of windows. $mod+n cycles through them; doesn't pop or consume.

Cycling: hidden → A → hidden → B → hidden → A → ….

Eviction

No dedicated "unstash" command. Both routes work because they violate the "floating + no workspace" property:

The killer pattern: auto-stash on launch

For a music player or chat app you always want one keystroke away:

for_window [app_id="^Cider$"] move scratchpad

Launch the app → it briefly flashes, then disappears into the scratchpad. $mod+n summons it whenever needed. Never wastes a workspace slot.

Bonus · Sticky

A sticky window stays visible on every workspace you switch to. Only applies to floaters.

This config already uses sticky for Picture-in-Picture videos:

for_window [title="^Picture in picture$"] floating enable, sticky enable, border pixel 2

Pop a YouTube video out into PiP — it floats AND sticks, so it follows you across workspaces. You've been using sticky daily without knowing the name.

Sticky vs scratchpad

Scratchpad = drawer. Pull it out when needed. Sticky = sticker. Always on the window.

If you ever want a manual sticky toggle, add: bindsym $mod+? sticky toggle to a free key.

Reading the matrix

Sway shows you the tree in tab titles when a container has only one child but sits inside wrapper containers. The shorthand:

So H[T[Alacritty]] = an H container, holding a T container, holding one Alacritty window. Three nodes nested; only one is visible.

What to do about orphans

Usually nothing. They don't affect rendering, focus navigation, or resize. They only bite when:

• A bracket key surprises you (extra wrapper changes what "the parent" is)
• Move-window has more layers to escape than expected
• A layout toggle changes scope you didn't intend

The fix in all cases is the same one tool: $mod+c to navigate to the right scope first.

Cheat sheet

Open and close

Focus & move

Layout

Resize

Workspaces

Scratchpad

System

Mouse (with $mod held)

Inspect the tree

# Compact view
swaymsg -t get_tree | grep -E '"(name|layout)"'

# Find an app's app_id
swaymsg -t get_tree | jq -r '.. | select(.type?=="con" or .type?=="floating_con") | "\(.app_id // .window_properties.class // "?")  ::  \(.name)"'

# Send commands directly (bypass keybinds)
swaymsg "resize grow width 100 px"
swaymsg "[app_id=firefox] focus"

You've finished sway school. Now go build weird layouts. 🌳