Learn Zellij - Floating Panes & Pane Frames

#Introduction

For the past five episodes, you've worked with tiled panes — panes that divide the screen like tiles: right, left, top, bottom. Every new pane forces another pane to shrink. In this episode you meet a fundamentally different concept: floating panes — panes that float above the layout like windows floating over a desktop, without forcing a single tiled pane to shift. This is the feature that makes Zellij unique in its class and most often captures the attention of people trying it for the first time.

Why do floating panes matter? There are tasks that are momentary by nature — checking one command's output, opening a reference file, looking at a calendar or calculator — and such tasks don't deserve a permanent half of the screen. With a floating pane, you open, use, then press one key to hide it. The tiled layout stays intact, and the floating context appears exactly when needed. In episode 5 you already touched pinning and stacking; in this episode both return in their full form in the floating realm.

This episode's map: first we create and toggle floating panes (Ctrl+p then w or Alt+f). Then we manage them — move, pin, persist. Next is embed/float (Ctrl+p then e), the two-way bridge between tiled and floating. After that, stacked floating panes for stacking many floating contexts. Finally, three visual control tools: layout swap (Alt+[ / Alt+]), frame toggle (Ctrl+p then z), and fullscreen (Ctrl+p then f). No configuration is needed — everything has been active since the 0.40s, and the latest 0.44.x version brings refinements to these features.

This difference in mental model is what makes floating panes feel empowering: a tiled pane always asks permission — opening one forces another to shrink. A floating pane doesn't. It takes empty space above the canvas, and when you're done, the canvas returns whole as if nothing happened. Many developers build an entire working style on this difference: everything momentary and temporary becomes floating, everything permanent and relied upon becomes tiled.

#Creating and Toggling Floating Panes

There are two doors into the floating world: Ctrl+p then w from Pane mode, and Alt+f directly from Normal mode. Both call the same action — ToggleFloatingPanes. The logic: if no floating pane exists, create one; if one exists, hide them all. This is smart design because one key manages both directions.

Note the subtle differences. Alt+f creates and displays the first floating pane. After that, Alt+n adds another floating pane — and because floating panes don't split the layout, each new Alt+n stacks on top of existing ones, floating over the work area. Move between them with Alt+h/j/k/l or Ctrl+p then h/j/k/l.

One thing to understand from the start: a floating pane isn't just "a rearranged tiled pane". It retains all pane semantics — scrollback, mode, even process state — but lives on a different layer. That's why it persists even when hidden: Zellij doesn't destroy a pane when it's hidden, it only lowers its visibility. This mental model answers almost all confusion around floating panes.

A floating pane isn't a passive object. It can be moved: drag its frame with the mouse, or use Move mode (Ctrl+h then h/j/k/l) to slide it with the keyboard. It can be resized the same way as a tiled pane (Ctrl+n or Alt+=/Alt+-). Essentially, a floating pane is a full pane with all regular pane capabilities — the only difference is its floating position.

Its placement behavior also differs from tiled. Tiled panes follow an auto-layout that tries to arrange space optimally; floating panes use free coordinates — set via the x, y, width, height options when opened from the CLI, or dragged with the mouse and Move mode. For complex floating layouts, Zellij even has a dedicated floating swap layout you can rotate with Alt+[ / Alt+]. Exploring both is the best way to feel the freedom tiled panes don't have.

zellij action new-pane --floating
zellij action toggle-floating-panes

#Pinned Floating Panes: Always on Top

Floating panes float, but some need to float above the others — always visible, never hidden behind another floating pane. Since Zellij 0.42, you have pinned floating panes for this need. A pinned floating pane "sticks" always at the top layer, like a panel pinned to the desktop.

When is this useful? Think of monitors you always want to watch: a streaming dev server log, watch uptime for a server, a team status panel, or a TODO reference. As long as that pane is pinned, other floating panes won't cover it. The indicator is easy to recognize — the pane frame shows a PIN label.

A concrete example: imagine a session running three floating panes — one streaming logs, one htop, one quick editor. Without pinning, when you open a new floating pane for another check, htop could be covered behind it. With htop pinned, it always stays in front, and the other panes just shift beneath it. This is the main reason the feature was born: turning a floating pane from "temporary" into "always visible" with one key, without changing its fundamental nature as a pane.

zellij action new-pane --floating --pinned true

Two equally valid paths, depending on whether the pane already exists or is newly opened:

zellij action toggle-pane-pinned

zellij action new-pane --floating --pinned true

Pinning doesn't change how other floating panes work — they can still be stacked and hidden as usual. What changes is the layer order: the pinned one is always frontmost. This is a precision tool for choosing "which information must never leave my sight".

#Embed and Float: Movement in Both Directions

Sometimes you're not sure whether a pane should be tiled or floating. Zellij's answer: you don't have to decide now. Ctrl+p then e (TogglePaneEmbedOrFloating) turns a floating pane into a regular tiled pane, and vice versa — the tiled pane you focus can be lifted into floating. This is a two-way bridge that makes moving between the two worlds feel costless.

The most common flow: you work with a tiled pane, realize one task needs more space, then lift that pane into floating temporarily. When done, embed it back to its original position. Zellij remembers the tiled layout — an embedded pane returns to its old slot.

Embedding also becomes the foundation of an interesting workflow with command panes. You can start a process in a floating pane, then embed it into the layout so it participates in layout swaps and splits — for example, lifting a team chat terminal into a settled tiled pane. Conversely, a pane running an editor can be lifted into floating briefly to stretch the screen, then embedded back. The tiled-or-floating decision becomes dynamic, following the workflow, not dogma.

zellij action toggle-pane-embed-or-floating
zellij action change-floating-pane-coordinates --pane-id terminal_3 --height 60% --width 60%

#Stacked Floating Panes: Stacking Floating Contexts

Several floating panes on the same screen can cover each other. Zellij solves this with stacked floating panes — a stack of floating panes in the same location that you can swap through quickly. This is an evolution of the stacking concept you learned in episode 5, but in the floating realm: instead of five scattered floating panes covering each other, you have one slot with five tidy layers.

It works intuitively. Open the first floating pane (Alt+f), then add another floating pane with Alt+n — Zellij stacks them according to the stacking rules. Move between layers with Alt+h/j/k/l or scroll. If you add many floating panes without specific coordinates, the result is a controlled stack, not chaos.

When many panes are in one stack, Zellij shows a list at the bottom of the screen (a feature controlled by the stacked_pane_list option, enabled by default). The currently displayed pane is pinned at the bottom of the list as a position marker. You move between layers with Alt+h/j/k/l, and scroll with the keys you already mastered in episode 6. If a stack feels suffocating, break it apart by embedding one of the layers into tiled — mixing tiled and floating is normal, not an anomaly.

For those who enjoy automation, zellij action stack-panes explicitly combines certain panes into one stack:

zellij action stack-panes -- terminal_1 terminal_2 terminal_3

When do stacked floating panes save your life? During debugging, when you need several inspection tools — htop, curl to an endpoint, and a log stream — without wanting all three to split the screen. Keep the three in one stack and take turns viewing them one by one. Many contexts, one screen.

#Layout Swap, Frame Toggle, and Fullscreen

The last part is full control over how space is displayed. Zellij has a list of swap layouts — layout arrangements that can be rotated to rearrange the currently visible panes. For tiled panes, press Alt+[ (previous layout) or Alt+] (next layout) and watch the panes rearrange themselves. Because Alt+[ / Alt+] also works on floating panes, you can rotate a floating stack the same way.

Frame toggle (Ctrl+p then z) hides or shows the boundary lines between panes. Zellij's default shows frames because they also carry pane names and status info — but some prefer a clean frameless look, especially on two panes whose boundaries are obvious. This option can also be changed permanently via pane_frames false in the config (fully covered in episode 8).

Fullscreen (Ctrl+p then f) zooms fully into the focused pane. A floating pane can go fullscreen too — the floating window explodes to fill the screen, then returns to its original size when toggled. The Shift+f version even hides the entire interface for pure focus.

All this arrangement behavior is powered by auto layout — Zellij tries to arrange panes automatically according to a set of built-in swap layouts that can be rotated. If this automatic layout doesn't suit you, the auto_layout option in the config can be turned off, and Alt+[ / Alt+] can still be used to rearrange manually. This is a combination worth understanding: auto layout is the default, swap layout is your manual control — and both work separately for tiled and floating panes.

#Common Pitfalls

1. Thinking Alt+f turns off a floating pane. It only hides it — the process keeps running. If you quit Zellij or close a tab with a hidden floating pane, the process inside ends too. Always consider that hidden doesn't mean stopped.
2. Letting floating panes pile up unpinned. Without pinning, floating panes can cover each other. Use Ctrl+p then i for ones that must always show, and stacking for ones that can be accessed alternately.
3. Forgetting that Ctrl+p then e works both ways. Lifting a tiled pane into floating is easy; what's often forgotten is embedding it back. This feature is the same key both directions — press once, don't press twice because you realize the layout changed.
4. Looking for a hidden floating pane. When floating panes are invisible, there's no visual hint on screen. Solution: press Alt+f to toggle back, or Ctrl+o then w to open the session-manager which shows pane states.
5. Thinking fullscreen erases the layout. Ctrl+p then f is temporary zoom; the layout is remembered. Some users panic and close a pane when they see the layout "disappear" — when in fact pressing f once more is all it takes.

#Closing

Floating panes are the feature that most often makes people fall in love with Zellij, and you now master the whole spectrum: creating and toggling (Alt+f), pinning for always-on-top, embedding and lifting (Ctrl+p then e), stacking neatly, plus three visual controls — layout swap, frames, and fullscreen. From this episode onward, your workspace is no longer static tiles, but a layered work space you can shape however you like.

Key takeaways:

• Floating: Ctrl+p then w or Alt+f to toggle; Alt+n to add.
• Pin: Ctrl+p then i so a floating pane is always on top.
• Embed/float: Ctrl+p then e to move in both directions.
• Visual: Alt+[/Alt+] layout swap, Ctrl+p then z frames, Ctrl+p then f fullscreen.

In episode 8 next, we stop pressing keys and start writing: you'll open ~/.config/zellij/, generate config.kdl with zellij setup --dump-config, understand the keybinds, options, and plugins blocks, and learn to reload configuration without restarting and save preferences through Session mode. See you in episode 8.