@viamrobotics/prime-panes
A layout of resizable, rearrangeable panes. layout is a tree that this package owns. A split divides its area between two children, a pane is a leaf that holds your data, a stack shows one of several panes behind tabs, and a float draws windows over a base layout. Every resize and rearrangement is assigned to layout, so bind it, or pass a getter and a setter to persist each change or veto it.
The pane snippet renders one pane, and the library never reads its content. Place Panes.DragTrigger and Panes.MoveTrigger in it so the pane can be rearranged with a pointer or without one, and Panes.TabList and Panes.PaneBody so it can stack with other panes.
The root has no default size, display, or styling. Size it with a class, or it collapses to nothing. Every other attribute of a div passes through to it.
Camera 1
Map
Log
Notes
Drag a divider to resize. Drag a grip onto another pane to rearrange, or onto its tab strip to stack. Drag a window's title to move it.
Code
<script lang="ts"> import type { LayoutNode, PaneNode, PaneState, } from "@viamrobotics/prime-panes";
import { addPaneToUpperRight, floatPane, Panes, removeFloat, removePane, } from "@viamrobotics/prime-panes";
interface PaneData { label: string; }
const WINDOW_RECT = { x: 24, y: 24, width: 200, height: 140 };
const leaf = (id: string, label: string): PaneNode<PaneData> => ({ type: "pane", id, data: { label }, });
const initial = (): LayoutNode<PaneData> => ({ type: "split", id: "root", direction: "row", ratio: 0.5, first: { type: "stack", id: "cameras", activeId: "camera-1", panes: [leaf("camera-1", "Camera 1"), leaf("camera-2", "Camera 2")], }, second: { type: "float", id: "dashboard", base: { type: "split", id: "readouts", direction: "column", ratio: 0.5, first: leaf("map", "Map"), second: leaf("log", "Log"), }, floats: [ { id: "notes-window", rect: { x: 16, y: 40, width: 200, height: 130 }, content: leaf("notes", "Notes"), }, ], }, });
let layout = $state<LayoutNode<PaneData> | undefined>(initial()); let added = 0;
function addPane() { added += 1; layout = addPaneToUpperRight( layout, leaf(`added-${added}`, `Pane ${added}`), `added-split-${added}`, ); }
function popOut(id: string) { added += 1; layout = floatPane( layout, id, WINDOW_RECT, `window-${added}`, `float-${added}`, ); }</script>
<div class="flex h-full flex-col gap-2"> <div class="flex items-center gap-2"> <button type="button" class="button" onclick={addPane}>Add pane</button> <button type="button" class="button" onclick={() => (layout = initial())}> Reset layout </button> </div>
<Panes bind:layout paneLabel={(node) => node.data.label} class="min-h-0 flex-1" > {#snippet empty()} <div class="flex size-full items-center justify-center text-sm text-subtle-2" > No panes. Add one to start. </div> {/snippet}
{#snippet pane(node: PaneNode<PaneData>, state: PaneState)} <div class="flex size-full flex-col border border-light bg-white text-sm text-default" > <header class="flex items-center gap-1 border-b border-light bg-light px-1 py-1" > <Panes.DragTrigger> <Panes.MoveTrigger aria-label="Move {node.data.label}" class="inline-flex size-6 cursor-grab items-center justify-center text-subtle-1 active:cursor-grabbing" > <svg viewBox="0 0 16 16" class="size-4" fill="currentColor" aria-hidden="true" > <circle cx="5.5" cy="3.5" r="1.25" /> <circle cx="10.5" cy="3.5" r="1.25" /> <circle cx="5.5" cy="8" r="1.25" /> <circle cx="10.5" cy="8" r="1.25" /> <circle cx="5.5" cy="12.5" r="1.25" /> <circle cx="10.5" cy="12.5" r="1.25" /> </svg> </Panes.MoveTrigger> </Panes.DragTrigger>
<Panes.DragTrigger target="float"> <div class="flex min-w-0 flex-1 items-center gap-1 self-stretch"> <h2 class="truncate px-1 text-xs font-semibold in-data-stacked:hidden" > {node.data.label} </h2> <Panes.TabList aria-label="Stacked panes" class="flex min-w-0 gap-1 text-xs" > <Panes.TabListDropRegion class="absolute inset-x-0 top-0 hidden h-4 border-t-2 border-dashed border-info-medium in-data-dragging:block in-data-move-mode:block" /> </Panes.TabList> </div> </Panes.DragTrigger>
{#if state.isStacked} <Panes.MoveTrigger target="stack" class="button px-2 py-0.5 text-xs"> Move stack </Panes.MoveTrigger> {/if}
{#if state.isFloating} <Panes.MoveTrigger target="float" aria-label="Dock {node.data.label}" class="button px-2 py-0.5 text-xs" > Dock </Panes.MoveTrigger> <button type="button" aria-label="Close {node.data.label}" class="inline-flex size-6 items-center justify-center text-subtle-1" onclick={() => (layout = removeFloat(layout, state.floatEntryId!))} > <svg viewBox="0 0 16 16" class="size-4" fill="none" stroke="currentColor" aria-hidden="true" > <path d="M4 4l8 8M12 4l-8 8" /> </svg> </button> {:else} <button type="button" aria-label="Remove {node.data.label}" class="inline-flex size-6 items-center justify-center text-subtle-1" onclick={() => (layout = removePane(layout, node.id))} > <svg viewBox="0 0 16 16" class="size-4" fill="none" stroke="currentColor" aria-hidden="true" > <path d="M4 4l8 8M12 4l-8 8" /> </svg> </button> {/if} </header>
<Panes.PaneBody class="flex min-h-0 flex-1 flex-col items-center justify-center gap-2 text-subtle-2" > {node.id} {#if !state.isFloating} <button type="button" class="button px-2 py-0.5 text-xs" onclick={() => popOut(node.id)} > Pop out </button> {/if} </Panes.PaneBody> </div> {/snippet} </Panes>
<p class="text-xs text-subtle-2"> Drag a divider to resize. Drag a grip onto another pane to rearrange, or onto its tab strip to stack. Drag a window's title to move it. </p></div>- The layout is a plain tree of objects that the package owns, with your
dataon each pane.bind:layoutreceives every resize and rearrangement, and a getter and setter pair can persist or veto each one. - Panes resize by dragging a divider or with the arrow keys, and rearrange by dragging or, without dragging, in move mode with a pointer, touch, the keyboard, or a screen reader.
- A slot can hold a stack of panes behind tabs, or windows that float over a base layout, and a
Panesview can sit inside a pane of another. - Pane content is yours. The library renders no header, grip, or window title bar, so you choose the markup, the icon, and the accessible name of each control.
Installation
Section titled “Installation”-
Install the package and its peers. The
sveltepeer is^5.29.0because the pane controls are attachments.@viamrobotics/tailwind-configcomes with the package as a dependency, and installing it directly as well gives your own classes the same tokens.Terminal window pnpm add @viamrobotics/prime-panes @viamrobotics/tailwind-config @zag-js/splitter @zag-js/floating-panel @zag-js/svelteTerminal window npm install @viamrobotics/prime-panes @viamrobotics/tailwind-config @zag-js/splitter @zag-js/floating-panel @zag-js/svelteTerminal window yarn add @viamrobotics/prime-panes @viamrobotics/tailwind-config @zag-js/splitter @zag-js/floating-panel @zag-js/svelte -
Import the package stylesheet once, after Tailwind. Tailwind skips
node_moduleswhen it scans for classes, so this file points it at the package’s compiled components and pulls in the@viamrobotics/tailwind-configtokens.@import "tailwindcss";@import "@viamrobotics/prime-panes/styles.css";
The examples on this page also use the button and input classes from @viamrobotics/tailwind-config and its color tokens, such as bg-light and text-subtle-2. The package styles only what it must, and each part that renders an element takes a class.
Anatomy
Section titled “Anatomy”Every part is a property on Panes, and every part goes inside the pane snippet, since each one connects to the pane it renders in. All of them are optional. Panes.DragTrigger and Panes.MoveTrigger rearrange the pane, Panes.TabList and Panes.TabListDropRegion stack it, and Panes.PaneBody marks its body. Panes.TabListDropRegion goes inside Panes.TabList. Panes.MoveTrigger can sit inside a Panes.DragTrigger or stand alone.
<Panes> {#snippet pane(node, state)} <Panes.DragTrigger> <Panes.MoveTrigger /> </Panes.DragTrigger> <Panes.TabList> <Panes.TabListDropRegion /> </Panes.TabList> <Panes.PaneBody /> {/snippet}</Panes>Panes also takes an empty snippet for a layout of undefined and a dragPreview snippet for the ghost that follows the pointer.
Two-way binding
Section titled “Two-way binding”Bind a $state variable to layout. Every resize and rearrangement updates it, and assigning to it from your code re-renders the view. The pane snippet renders one pane. paneLabel names each pane for the move notice, the previews, and the announcements described under Moving panes without dragging. The root has no default size, so give it one with a class, or it collapses to nothing. Every other prop of a div passes through to the root.
{
"type": "split",
"id": "root",
"direction": "row",
"ratio": 0.6,
"first": {
"type": "pane",
"id": "camera",
"data": {
"title": "Camera"
}
},
"second": {
"type": "pane",
"id": "stats",
"data": {
"title": "Stats"
}
}
}Code
<script lang="ts"> import type { LayoutNode } from "@viamrobotics/prime-panes";
import { Panes } from "@viamrobotics/prime-panes";
interface PaneData { title: string; }
let layout = $state<LayoutNode<PaneData> | undefined>({ type: "split", id: "root", direction: "row", ratio: 0.6, first: { type: "pane", id: "camera", data: { title: "Camera" } }, second: { type: "pane", id: "stats", data: { title: "Stats" } }, });</script>
<div class="flex h-full flex-col gap-3"> <Panes bind:layout paneLabel={(node) => node.data.title} class="min-h-0 flex-1" > {#snippet pane(node)} <div class="flex size-full flex-col border border-light bg-white"> <Panes.DragTrigger> <header class="flex cursor-grab items-center gap-2 border-b border-light bg-light px-2 py-1 text-xs font-semibold text-default" > {node.data.title} <Panes.MoveTrigger aria-label="Move {node.data.title}" class="button ml-auto px-2 py-0.5 text-xs font-normal" > Move </Panes.MoveTrigger> </header> </Panes.DragTrigger> </div> {/snippet} </Panes>
<pre class="h-28 shrink-0 overflow-auto rounded-sm border border-light bg-light p-2 text-xs text-default">{JSON.stringify( layout, null, 2, )}</pre></div>The layout model
Section titled “The layout model”A layout is a tree of four node types. This section covers splits and panes, Stacks covers stacks, and Floating panes covers floats.
type SplitDirection = "row" | "column";
interface SplitNode<TData> { type: "split"; id: string; direction: SplitDirection; ratio: number; first: LayoutNode<TData>; second: LayoutNode<TData>;}
interface PaneNode<TData> { type: "pane"; id: string; data: TData;}
type LayoutNode<TData> = | SplitNode<TData> | PaneNode<TData> | StackNode<TData> | FloatNode<TData>;- A
SplitNodedivides its area betweenfirstandsecond. directionfollows CSSflex-direction. In arowsplit,firstis on the left. In acolumnsplit,firstis on top.ratiois the share given tofirst. It is strictly between 0 and 1.idis unique across the whole layout: splits, panes, stacks, floats, and float entries together.- A
PaneNodeis a leaf. Itsdatais any value you choose. It is the genericTData, and thepanesnippet receives it back. - A layout of
undefinedis an empty layout.
The pane snippet
Section titled “The pane snippet”The pane snippet renders one pane. Its first argument is the PaneNode, so node.id and node.data are available. Its second is the pane’s PaneState, described below. The snippet’s content fills the pane, so give it size-full or an equivalent.
The optional empty snippet renders when layout is undefined.
<Panes bind:layout class="h-screen"> {#snippet pane(node)}...{/snippet} {#snippet empty()} <p>No panes. Add one to start.</p> {/snippet}</Panes>The values of PaneState are reactive, so markup that reads them updates in place.
| Value | True when | Attribute |
|---|---|---|
isStacked |
The pane shares its slot with other panes in a stack. | data-stacked |
isMoving |
The pane, or its whole stack, is being moved in move mode. | data-moving |
isDragArmed |
A press has armed the pane to drag. | data-drag-armed |
isFloating |
The pane is inside a float entry, at any depth. | data-floating |
floatEntryId is the id of the innermost float entry that holds the pane, for removeFloat and raiseFloat. It is undefined outside a float.
Each value also appears as an attribute on the pane’s wrapper. Use the attribute to restyle, and the argument when markup or logic depends on the state. In a stack, the tabs can stand in for the pane’s title.
{#snippet pane(node, state)} <header> {#if !state.isStacked}<h2>{node.data.label}</h2>{/if} <Panes.TabList aria-label="Stacked panes" /> </header>{/snippet}With the attribute alone, the same title is <h2 class="in-data-stacked:hidden">.
Function binding
Section titled “Function binding”Panes has no change callback. State flows through bind:layout, which works in two modes: a $state variable, as above, or a getter and a setter. The setter receives each proposed layout. It is where you persist the change, and it can veto a change by not assigning the value. A vetoed change leaves the layout where it was, and a drag that is vetoed snaps back. Persisting a layout builds a save on this.
0 proposed, 0 rejected
Code
<script lang="ts"> import type { LayoutNode } from "@viamrobotics/prime-panes";
import { Panes } from "@viamrobotics/prime-panes";
interface PaneData { title: string; }
type Layout = LayoutNode<PaneData> | undefined;
let layout = $state<Layout>({ type: "split", id: "root", direction: "row", ratio: 0.5, first: { type: "pane", id: "camera", data: { title: "Camera" } }, second: { type: "pane", id: "stats", data: { title: "Stats" } }, }); let isLocked = $state(false); let proposed = $state(0); let rejected = $state(0);
function propose(next: Layout) { proposed += 1; if (isLocked) { rejected += 1; return; } layout = next; }</script>
<div class="flex h-full flex-col gap-3"> <label class="flex items-center gap-2 text-sm text-default"> <input type="checkbox" bind:checked={isLocked} /> Lock the layout </label>
<Panes bind:layout={() => layout, propose} paneLabel={(node) => node.data.title} class="min-h-0 flex-1" > {#snippet pane(node)} <div class="flex size-full flex-col border border-light bg-white"> <Panes.DragTrigger> <header class="flex cursor-grab items-center gap-2 border-b border-light bg-light px-2 py-1 text-xs font-semibold text-default" > {node.data.title} <Panes.MoveTrigger aria-label="Move {node.data.title}" class="button ml-auto px-2 py-0.5 text-xs font-normal" > Move </Panes.MoveTrigger> </header> </Panes.DragTrigger> </div> {/snippet} </Panes>
<p class="text-sm text-subtle-2" aria-live="polite"> {proposed} proposed, {rejected} rejected </p></div>With the layout locked, the setter counts each proposal and assigns none of them, so a resize or a drop does not stick. Rearranging through move mode goes through the same setter.
Drag and move triggers
Section titled “Drag and move triggers”Rearranging is on by default. Set reorderable={false} to turn it off. Resizing is not affected. Two parts that you place inside the pane snippet connect your markup to the pane. Panes.DragTrigger makes the elements inside it start a pointer drag, and Panes.MoveTrigger toggles move mode, the way to rearrange without dragging. Both do nothing when reorderable is false.
The two can be laid out in two ways, and the example shows both. A grip can sit inside a Panes.DragTrigger as a Panes.MoveTrigger, so dragging and the keyboard path share one element. A press on it drags at once, and a click without movement enters move mode. Or a whole header can be the drag surface, with a separate move button inside it. A press on the header drags at once, and a quick click on the button still moves.
Grip
Header
Code
<script lang="ts"> import type { LayoutNode } from "@viamrobotics/prime-panes";
import { Panes } from "@viamrobotics/prime-panes";
interface PaneData { title: string; variant: "grip" | "header"; hint: string; }
let layout = $state<LayoutNode<PaneData> | undefined>({ type: "split", id: "root", direction: "row", ratio: 0.5, first: { type: "pane", id: "grip", data: { title: "Grip", variant: "grip", hint: "Press the grip to drag. Click it to move.", }, }, second: { type: "pane", id: "header", data: { title: "Header", variant: "header", hint: "Press the header to drag. Click Move to move.", }, }, });</script>
<Panes bind:layout paneLabel={(node) => node.data.title} class="h-full"> {#snippet pane(node)} <div class="flex size-full flex-col border border-light bg-white text-sm text-default" > {#if node.data.variant === "grip"} <header class="flex items-center gap-1 border-b border-light bg-light px-1 py-1" > <Panes.DragTrigger> <Panes.MoveTrigger aria-label="Move {node.data.title}" class="inline-flex size-6 cursor-grab items-center justify-center text-subtle-1 active:cursor-grabbing" > <svg viewBox="0 0 16 16" class="size-4" fill="currentColor" aria-hidden="true" > <circle cx="5.5" cy="3.5" r="1.25" /> <circle cx="10.5" cy="3.5" r="1.25" /> <circle cx="5.5" cy="8" r="1.25" /> <circle cx="10.5" cy="8" r="1.25" /> <circle cx="5.5" cy="12.5" r="1.25" /> <circle cx="10.5" cy="12.5" r="1.25" /> </svg> </Panes.MoveTrigger> </Panes.DragTrigger> <h2 class="text-xs font-semibold">{node.data.title}</h2> </header> {:else} <Panes.DragTrigger> <header class="flex cursor-grab items-center gap-1 border-b border-light bg-light px-2 py-1 active:cursor-grabbing" > <h2 class="text-xs font-semibold">{node.data.title}</h2> <Panes.MoveTrigger aria-label="Move {node.data.title}" class="button ml-auto px-2 py-0.5 text-xs" > Move </Panes.MoveTrigger> </header> </Panes.DragTrigger> {/if} <div class="flex min-h-0 flex-1 items-center justify-center p-3 text-center text-xs text-subtle-2" > {node.data.hint} </div> </div> {/snippet}</Panes>While a pane is ready to drag, it shows a blue outline and its wrapper carries data-drag-armed. Style your own markup from it with a selector such as [data-drag-armed] header, or with Tailwind’s in-data-drag-armed: variant.
Excluding an element from dragging
Section titled “Excluding an element from dragging”dragIgnore opts an element out of dragging. Import it from the package root. It is an attachment that needs no context. Use it on a custom widget inside a Panes.DragTrigger, such as a canvas, where a press should do something else.
<script lang="ts"> import { dragIgnore } from "@viamrobotics/prime-panes";</script>
<canvas {@attach dragIgnore}></canvas>Accessibility
Section titled “Accessibility”Dragging alone fails WCAG 2.5.7 (Dragging Movements). Every pane that has a Panes.DragTrigger needs a Panes.MoveTrigger somewhere, such as a menu item. A drag that moves a stack needs one with target="stack", and a drag that moves a window needs one with target="float". Render one in each pane that can host the drag.
In development, the library warns on the first drag from a pane that has no move trigger for what the drag moves. A trigger that mounts only on demand, such as inside a menu, still warns until it first mounts.
Panes: a stack drag started in pane "Camera A", which has no Panes.MoveTrigger with target="stack". Dragging alone fails WCAG 2.5.7 (Dragging Movements), so render a Panes.MoveTrigger with target="stack" in the pane to move its stack without dragging. A Panes.MoveTrigger that mounts only on demand, such as inside a menu, still triggers this warning until it first mounts.Drop regions
Section titled “Drop regions”While a pane is dragged, the pane under the pointer divides into regions.
| Region | Result |
|---|---|
| Center (the middle 40%) | The two slots swap places. A stack swaps as a whole. |
| Left, right, top, or bottom | The dragged pane leaves its place and splits the target, on the side that you drop. |
Panes.TabListDropRegion |
The dragged pane stacks with the target. See Stacks. |
Every drop is assigned to layout, so a function binding sees it and can veto it.
Escape, a pointer cancel, the window losing focus, and a release outside every pane cancel the drag. layout stays as it was.
The drag preview
Section titled “The drag preview”A ghost follows the pointer during a drag. It shows the pane’s label, or a stack’s labels joined. The library positions it in the top layer, keeps it from taking pointer events, and makes it inert and hidden from assistive technology.
The ghost shows what a drop would make. Over a tab strip or a Panes.TabListDropRegion, a drop makes a tab, and the ghost is a tab chip. Anywhere else, a drop makes a pane, and the ghost is a pane card. The ghost root carries data-form with the value tab or pane, so you can style each form.
The dragPreview snippet on Panes replaces the ghost’s content. It receives a DragPreview with a type of 'pane' or 'stack', a form of 'tab' or 'pane', the dragged panes, and the label. Keep it free of controls, since nothing inside the ghost can take focus.
<Panes bind:layout class="h-screen"> {#snippet dragPreview({ form, label, panes })} {#if form === "tab"} <span class="rounded-t bg-white px-2 py-1 shadow-sm">{label}</span> {:else} <span class="rounded-sm bg-white px-3 py-2 shadow-sm">{label} ({panes.length})</span> {/if} {/snippet}</Panes>While a drag that can drop onto panes is active, the root carries data-dragging, beside data-move-mode, for styling. Repositioning a floating window and a Shift drag that floats drop onto no pane, so they do not set it.
Moving panes without dragging
Section titled “Moving panes without dragging”Dragging is not the only way to rearrange. Activate a Panes.MoveTrigger with a click, Enter, or Space to enter move mode. A button trigger reports it with aria-pressed.
Activating the trigger moves focus to the moving pane, which shows a blue focus outline, a light gray wash over its content, and “Moving Camera. Choose a destination with the pointer or arrow keys, or press Escape.” Every other pane becomes a destination that shows nothing until it is hovered or focused. A placement makes the same change a drop on that region would, and it goes through layout the same way, so a function binding can still veto it.
- With a pointer, the region under the pointer previews with the drag indicator and the moving pane’s label. A stack onto a stacked pane previews as a tab in its strip instead. A click places.
- On touch, a first tap previews a region and a second tap on the same region places.
- With the keyboard, focus stays on the moving pane’s trigger. An arrow key there moves into the adjacent pane, entering at its near edge. Each destination is a labeled group with one Tab stop. Within a pane, the horizontal arrows step left, center (swap), and right, and the vertical arrows step top, center, and bottom. Past the far edge, an arrow crosses into the next pane on screen, so panes that do not touch are reachable. The moving pane is skipped, and nothing wraps at the outer edge. Enter or Space places, and Tab moves between destinations.
- Arrows inside a text field in the moving pane stay with the field.
- Clicking an edge bar places the moving pane on that side.
- A screen reader in browse mode can reach and activate each side button.
- Escape cancels move mode. So does activating the pressed trigger again.
- Destination content is inert during move mode.
- A keyboard-started move keeps focus on the trigger, and focus returns to it when move mode ends.
- Moving focus out of the view cancels move mode. Focus stays where it moved.
- A status region announces each step: the start, the placement, a cancel, and a rejected move.
- A stacked pane’s own slot offers a reorder placement with positions. See Reordering tabs.
To restyle move mode, use data-move-mode on the root, which is present while move mode is active, and data-moving on the moving pane.
Set paneLabel so these read well. The notice, previews, and announcements use pane labels, such as “Camera placed left of Stats.”. paneLabel receives the PaneNode and returns a string. Without it the labels are pane ids.
<Panes bind:layout paneLabel={(node) => node.data.title}> {#snippet pane(node)}...{/snippet}</Panes>Stacks
Section titled “Stacks”A stack puts several panes in one slot behind tabs, such as three cameras in one camera area. In the example, switch tabs with a click or the arrow keys. Type in a field and switch away to see what unmounting loses, then turn on keeping inactive panes mounted and try again. Drag the Notes grip onto the top of the cameras’ header to stack it too.
Camera A
Notes
Code
<script lang="ts"> import type { LayoutNode, PaneNode, PaneState, } from "@viamrobotics/prime-panes";
import { Panes } from "@viamrobotics/prime-panes";
interface PaneData { label: string; }
const leaf = (id: string, label: string): PaneNode<PaneData> => ({ type: "pane", id, data: { label }, });
let layout = $state<LayoutNode<PaneData> | undefined>({ type: "split", id: "root", direction: "row", ratio: 0.6, first: { type: "stack", id: "cameras", activeId: "camera-a", panes: [ leaf("camera-a", "Camera A"), leaf("camera-b", "Camera B"), leaf("camera-c", "Camera C"), ], }, second: leaf("notes", "Notes"), }); let keepInactiveMounted = $state(false);</script>
<div class="flex h-full flex-col gap-3"> <label class="flex items-center gap-2 text-sm text-default"> <input type="checkbox" bind:checked={keepInactiveMounted} /> Keep inactive panes mounted </label>
<Panes bind:layout {keepInactiveMounted} paneLabel={(node) => node.data.label} class="min-h-0 flex-1" > {#snippet pane(node: PaneNode<PaneData>, state: PaneState)} <div class="flex size-full flex-col border border-light bg-white text-sm text-default" > <header class="flex items-center gap-1 border-b border-light bg-light px-1 py-1" > <Panes.DragTrigger> <Panes.MoveTrigger aria-label="Move {node.data.label}" class="inline-flex size-6 cursor-grab items-center justify-center text-subtle-1 active:cursor-grabbing" > <svg viewBox="0 0 16 16" class="size-4" fill="currentColor" aria-hidden="true" > <circle cx="5.5" cy="3.5" r="1.25" /> <circle cx="10.5" cy="3.5" r="1.25" /> <circle cx="5.5" cy="8" r="1.25" /> <circle cx="10.5" cy="8" r="1.25" /> <circle cx="5.5" cy="12.5" r="1.25" /> <circle cx="10.5" cy="12.5" r="1.25" /> </svg> </Panes.MoveTrigger> </Panes.DragTrigger> <h2 class="text-xs font-semibold in-data-stacked:hidden"> {node.data.label} </h2> <Panes.TabList aria-label="Stacked panes" class="flex min-w-0 gap-1 text-xs" > <Panes.TabListDropRegion class="absolute inset-x-0 top-0 hidden h-4 border-t-2 border-dashed border-info-medium in-data-dragging:block in-data-move-mode:block" /> </Panes.TabList> {#if state.isStacked} <Panes.MoveTrigger target="stack" class="button ml-auto px-2 py-0.5 text-xs" > Move stack </Panes.MoveTrigger> {/if} </header>
<Panes.PaneBody class="flex min-h-0 flex-1 flex-col justify-center p-3"> <input class="input" aria-label="Note for {node.data.label}" placeholder="Type here, then switch tabs" /> </Panes.PaneBody> </div> {/snippet} </Panes></div>The stack node
Section titled “The stack node”interface StackNode<TData> { type: "stack"; id: string; panes: PaneNode<TData>[]; activeId: string;}- A stack holds at least two panes. A stack that drops to one pane collapses to that pane.
- A stack holds panes only. It never holds a split or another stack.
panesis in tab order.activeIdis the id of the shown pane, and it is one ofpanes. If it names none of them, such as after a pane is renamed in a saved layout, the stack shows its first pane, and selecting a tab repairsactiveId.- The shown tab lives in the layout, so it persists with the rest and goes through
bind:layout. A function binding can veto a tab change.
A stack renders its active pane through your pane snippet. Inactive panes unmount.
const layout: LayoutNode<PaneData> = { type: "stack", id: "cameras", activeId: "camera-a", panes: [ { type: "pane", id: "camera-a", data: { label: "Camera A" } }, { type: "pane", id: "camera-b", data: { label: "Camera B" } }, { type: "pane", id: "camera-c", data: { label: "Camera C" } }, ],};Tabs and the pane body
Section titled “Tabs and the pane body”Panes.TabList renders the tabs of the stack that its pane belongs to, so place it in the pane snippet, usually in the header. It renders in every pane, so every pane can include it. The tablist role and the tabs appear only when the pane is stacked. An unstacked pane still carries the container, so it can be a stack target. Selecting is automatic, so focusing a tab with the arrows shows its pane, and a click selects too. Keyboard lists the keys.
Panes.PaneBody marks the part of the pane below its header. In a stacked pane with a Panes.TabList it becomes the tabpanel that the tabs control, so a screen reader announces the panel on entry. It is optional. Without it, the tabs still work and nothing claims the tabpanel role. Its rect also sets the edges and center of the pane’s drop regions, as Forming a stack describes.
Keeping inactive panes mounted
Section titled “Keeping inactive panes mounted”Inactive panes unmount by default, so their content restarts when its tab is shown again. Set keepInactiveMounted on Panes to keep them mounted. They stay hidden and inert.
<Panes bind:layout keepInactiveMounted class="h-screen"> {#snippet pane(node)}...{/snippet}</Panes>The prop applies to every stack in the view. Use it for content that is costly to rebuild, such as a live video stream.
Forming a stack
Section titled “Forming a stack”Drop a pane onto a pane’s Panes.TabListDropRegion to stack it there. A pane without one never stacks. On an unstacked pane, the drop indicator covers the region’s rect. A stacked pane previews the drop as a tab in its strip instead and leaves the region untinted, so the tab labels stay readable while you place. The center of a pane still swaps, and the edges still split. Over a stacked target’s region, a preview tab shows where the dropped pane will land, and the drop inserts it there. See Inserting at a position.
Place the region inside Panes.TabList. Size and position it with class. Three placements work:
- A visible strip over the tabs.
- A grip area.
- An edge strip that shows only during a drag.
A region shown only during a drag should also show in move mode, so move mode can stack there. The root’s data-dragging and data-move-mode attributes drive the styles. The first hit test after a drag starts misses a region that was hidden before, and the next pointer move finds it. The example’s strip sits along the very top edge of the pane, and the pane’s wrapper is the positioned ancestor.
<Panes.TabList aria-label="Stacked panes" class="flex gap-1"> <Panes.TabListDropRegion class="absolute inset-x-0 top-0 hidden h-4 in-data-dragging:block in-data-move-mode:block" /></Panes.TabList>Panes.PaneBody’s rect sets the edges and center. A point inside the pane but outside the body, such as the header, reads as the nearest edge, so a header above the body reads as the top edge. With no Panes.PaneBody, the whole pane applies. The region wins wherever it overlaps the body. Edge and center indicators still cover the whole pane, since the split acts on the whole slot.
Center always swaps whole slots. A tab dropped on another pane’s center moves its whole stack, which trades places with the target. To move one tab alone, drop it on an edge or on a region. A pane dropped on a stack’s center trades places with the whole stack.
Without a position, the dragged pane joins the end of the target’s tab order and becomes the shown pane. If the target is not stacked yet, a new stack holds the target first and the dragged pane second. Dragging a stack onto a region merges the whole stack into the target, and it shows the dragged stack’s active pane.
Forming a stack in move mode
Section titled “Forming a stack in move mode”Move mode offers “Stack with” on each destination. See Moving panes without dragging. Press the arrow toward the region’s side to reach it. The side comes from the region’s rect against the Panes.PaneBody rect. For a strip along the top edge that is the up arrow, and a second up arrow crosses to the pane above. “Stack with” is offered wherever a region is mounted.
On a stacked target, “Stack with” takes a position, and the default is the end. The arrows along the strip pick a gap between tabs. At either end of the strip, the next arrow continues to the next region. The button name carries the position, such as “Stack Camera A with Log at position 2 of 4”. An unstacked target has one position, so its name carries none.
The wording follows the placement. On an unstacked target the preview reads “Stack Camera with Stats”, and the announcement reads “Camera stacked with Stats.”.
Placing on a stacked pane
Section titled “Placing on a stacked pane”- Center on a stacked pane swaps the dragged pane with the whole stack. A dragged tab moves its whole stack to the target’s center.
- An edge places the dragged pane beside the whole stack, not beside one tab.
- Dragging or moving a stacked pane elsewhere removes it from its stack. A stack left with one pane collapses.
Dragging a tab
Section titled “Dragging a tab”A tab drags its own pane once the pointer moves 4px. There is no hold. A press without movement selects the tab, however long it lasts.
Reordering tabs
Section titled “Reordering tabs”Dragging a tab over its own strip lifts it out. A preview tab marks the insertion point, and the other tabs shift to make room. The shift is animated, and it is instant under prefers-reduced-motion.
Dropping reorders the stack, and the dropped pane becomes the active pane.
For a keyboard path, press Alt + Shift + ArrowLeft or Alt + Shift + ArrowRight on a focused tab to move it one place. Focus stays on the tab, and a status message announces the move.
In move mode, the own slot of a stacked moving pane offers a reorder placement with positions. See Forming a stack in move mode.
Inserting at a position
Section titled “Inserting at a position”Over another pane’s Panes.TabListDropRegion, the preview tab shows at the pointer’s position, and the drop inserts the pane there.
- A region along the top or bottom of the body inserts at the pointer’s x.
- A region along the left or right of the body appends.
- An unstacked target appends, with no preview.
- Insertion runs along a horizontal strip only.
Moving a whole stack
Section titled “Moving a whole stack”The empty area of a Panes.TabList drags the whole stack. So does a Panes.DragTrigger with target="stack". A Panes.MoveTrigger with target="stack" moves the whole stack in move mode. Both take target as "pane", "stack", or "float", and the default is "pane". On a pane that is not stacked, target="stack" acts as target="pane". Inside a floating window, Panes.MoveTrigger also takes target="float", which moves the window’s pane or stack. See Windows and assistive technology.
<Panes.MoveTrigger target="stack">Move stack</Panes.MoveTrigger>A moving stack is named by its panes’ labels, such as “Camera A, Camera B, and Camera C”.
| Drop or placement on a target | Result |
|---|---|
| An edge | The stack lands beside the target’s slot. |
| Center | The stack swaps with the target’s whole slot. |
A Panes.TabListDropRegion |
The stack merges into the target’s stack. |
Unstacking beside its own stack
Section titled “Unstacking beside its own stack”Dropping a stacked pane on an edge of its own stack takes it out of the stack and places it beside the rest. In move mode, the own slot of a stacked moving pane offers its four edges, which gives this a keyboard path. It also offers a reorder, one ArrowUp past the top edge, named like “Move Camera A to position 1 of 3”. The reorder starts at the pane’s current position, and a reorder announces “Camera A moved to position 3 of 3.”
Floating panes
Section titled “Floating panes”A float node draws windows over a base layout, such as a small camera view that sits above a dashboard. In the example, drag a window’s title to move it, drag its edges or corners to resize it, and use the buttons in its body to do the same with single clicks. Pop out floats a pane from the base, and Dock starts a move of a window’s pane, so you choose where it docks.
Map
Telemetry
Camera
Code
<script lang="ts"> import type { FloatRect, LayoutNode, PaneNode, PaneState, } from "@viamrobotics/prime-panes";
import { floatPane, Panes, removeFloat, setFloatRect, } from "@viamrobotics/prime-panes";
interface PaneData { label: string; }
const STEP = 40; const NEW_WINDOW: FloatRect = { x: 24, y: 24, width: 240, height: 160 }; const ADJUSTMENTS = [ { label: "Narrower", change: (rect: FloatRect) => ({ ...rect, width: rect.width - STEP }), }, { label: "Wider", change: (rect: FloatRect) => ({ ...rect, width: rect.width + STEP }), }, { label: "Left", change: (rect: FloatRect) => ({ ...rect, x: rect.x - STEP }), }, { label: "Right", change: (rect: FloatRect) => ({ ...rect, x: rect.x + STEP }), }, ];
const leaf = (id: string, label: string): PaneNode<PaneData> => ({ type: "pane", id, data: { label }, });
let layout = $state<LayoutNode<PaneData> | undefined>({ type: "float", id: "dashboard", base: { type: "split", id: "base", direction: "column", ratio: 0.5, first: leaf("map", "Map"), second: leaf("telemetry", "Telemetry"), }, floats: [ { id: "camera-window", rect: { x: 24, y: 24, width: 240, height: 160 }, content: leaf("camera", "Camera"), }, ], }); let opened = 0;
function popOut(paneId: string) { opened += 1; layout = floatPane( layout, paneId, NEW_WINDOW, `window-${opened}`, `float-${opened}`, ); }
function adjust(entryId: string, change: (rect: FloatRect) => FloatRect) { layout = setFloatRect(layout, entryId, change); }</script>
<Panes bind:layout paneLabel={(node) => node.data.label} class="h-full"> {#snippet pane(node: PaneNode<PaneData>, state: PaneState)} <div class="flex size-full flex-col border border-light bg-white text-sm text-default" > <header class="flex items-center gap-1 border-b border-light bg-light px-1 py-1" > <Panes.DragTrigger> <Panes.MoveTrigger aria-label="Move {node.data.label}" class="inline-flex size-6 cursor-grab items-center justify-center text-subtle-1 active:cursor-grabbing" > <svg viewBox="0 0 16 16" class="size-4" fill="currentColor" aria-hidden="true" > <circle cx="5.5" cy="3.5" r="1.25" /> <circle cx="10.5" cy="3.5" r="1.25" /> <circle cx="5.5" cy="8" r="1.25" /> <circle cx="10.5" cy="8" r="1.25" /> <circle cx="5.5" cy="12.5" r="1.25" /> <circle cx="10.5" cy="12.5" r="1.25" /> </svg> </Panes.MoveTrigger> </Panes.DragTrigger>
<Panes.DragTrigger target="float"> <h2 class="min-w-0 flex-1 self-stretch truncate px-1 text-xs font-semibold in-data-floating:cursor-move" > {node.data.label} </h2> </Panes.DragTrigger>
{#if state.isFloating} <Panes.MoveTrigger target="float" aria-label="Dock {node.data.label}" class="button px-2 py-0.5 text-xs" > Dock </Panes.MoveTrigger> <button type="button" aria-label="Close {node.data.label}" class="inline-flex size-6 items-center justify-center text-subtle-1" onclick={() => (layout = removeFloat(layout, state.floatEntryId!))} > <svg viewBox="0 0 16 16" class="size-4" fill="none" stroke="currentColor" aria-hidden="true" > <path d="M4 4l8 8M12 4l-8 8" /> </svg> </button> {:else} <button type="button" class="button px-2 py-0.5 text-xs" onclick={() => popOut(node.id)} > Pop out </button> {/if} </header>
<Panes.PaneBody class="flex min-h-0 flex-1 flex-wrap content-center items-center justify-center gap-1 p-2" > {#if state.isFloating} {#each ADJUSTMENTS as adjustment (adjustment.label)} <button type="button" class="button min-h-6 px-2 py-0.5 text-xs" onclick={() => adjust(state.floatEntryId!, adjustment.change)} > {adjustment.label} </button> {/each} {/if} </Panes.PaneBody> </div> {/snippet}</Panes>The float node
Section titled “The float node”interface FloatNode<TData> { type: "float"; id: string; base?: LayoutNode<TData>; floats: FloatEntry<TData>[];}
interface FloatEntry<TData> { id: string; rect: FloatRect; content: LayoutNode<TData>;}
interface FloatRect { x: number; y: number; width: number; height: number;}- A float node draws its windows over
base, inside the float node’s own box. Nothing portals out of that box. basefills the box behind the windows. It is absent once its last pane leaves.- Each entry in
floatsis one window. Itscontentis any layout node, so a window can hold a pane, a stack, or a split. rectis in pixels, relative to the float node’s box.- Stacking order is array order. The last entry is on top.
- A rect that reaches past the box renders clamped to it. The stored rect never changes.
- An entry’s
idis unique within the layout. It stays the same when a drop replaces the entry’scontent. - A float node holds at least one entry. When its last entry leaves, the float node collapses to its
base.
const layout: LayoutNode<PaneData> = { type: "float", id: "dashboard", base: { type: "pane", id: "map", data: { label: "Map" } }, floats: [ { id: "camera-window", rect: { x: 24, y: 24, width: 320, height: 200 }, content: { type: "pane", id: "camera", data: { label: "Camera" } }, }, ],};Float operations
Section titled “Float operations”Five operations edit float nodes. Like the other tree operations, each is immutable, returns the same root reference when nothing changed, and returns undefined for an undefined root.
floatPane(root, paneId, rect, newEntryId, newFloatId, hostId?)floatStack(root, stackId, rect, newEntryId, newFloatId, hostId?)setFloatRect(root, entryId, rect)raiseFloat(root, entryId)removeFloat(root, entryId)floatPanemoves a pane out of its slot into a new window.newEntryIdis the id of the new entry.floatStackdoes the same for a whole stack, which becomes the window’scontent.hostIdis the node whose box the window floats over. It defaults to the root. When the host is not a float node,floatPaneandfloatStackwrap it in a new float node with the idnewFloatId. When the host is a float node, the window joins it andnewFloatIdgoes unused.setFloatRectreplaces an entry’s rect. It also takes an updater,(rect) => rect, that receives the current rect.raiseFloatmoves an entry to the top of its float node’s stacking order.removeFloatremoves an entry and everything in it.
The operations never create ids. Create them at the call site.
function popOut(paneId: string) { layout = floatPane( layout, paneId, { x: 24, y: 24, width: 320, height: 200 }, crypto.randomUUID(), crypto.randomUUID(), );}Docking needs no operation. Dragging a floating pane onto a base pane is a movePane drop, so movePane and the other move operations take a pane out of a window like any other slot.
Moving and resizing windows
Section titled “Moving and resizing windows”Wrap a window’s title bar in Panes.DragTrigger with target="float" to make it a handle for the window that holds the pane. On a pane outside a window it acts as target="pane", so one header works in both places, as the example’s does.
{#snippet pane(node, state)} <header> {#if state.isFloating} <Panes.DragTrigger target="float"> <h2>{node.data.label}</h2> </Panes.DragTrigger> {:else} <h2>{node.data.label}</h2> {/if} </header>{/snippet}The window moves live under the pointer. No ghost and no drop regions appear, and layout receives the new rect once, on release. A function binding that vetoes the write snaps the window back.
target="pane" and target="stack" keep their meaning inside a window. They drag the pane or stack out with the ghost, so it can dock.
Shift inverts a drag. In a window, a target="float" drag with Shift held docks instead. It shows the ghost and the drop regions, and docks the window’s pane or stack. From the base, a drag with Shift held floats the pane or stack over the root at its current size, where it is released, instead of docking it.
Every window has eight resize handles, on its edges and corners. Each carries data-float-resize with its axis, one of n, e, s, w, ne, nw, se, or sw, so you can style them. A resize writes the rect once, on release.
[data-float-resize]:hover { background-color: var(--color-info-light);}floatMinSize is a prop of Panes. It receives the window’s FloatEntry and returns the smallest size the window can have. It defaults to 160 by 120 pixels.
<Panes bind:layout {pane} floatMinSize={(entry) => entry.content.type === "stack" ? { width: 320, height: 200 } : { width: 240, height: 160 }}/>Resizing stops at that size, and a window is never drawn smaller than it, unless the float node’s box is smaller.
Windows and assistive technology
Section titled “Windows and assistive technology”Each window is a non-modal role="dialog" and can take focus. Its name is paneLabel of the panes it holds. A stack’s labels are joined, as they are in the drag ghost. With the window itself focused, the arrow keys move and resize it. Keyboard lists them. Each key press writes layout once, so a function binding can veto it. Keys typed in a control inside the window stay with that control. Keyboard moves and resizes announce nothing.
In move mode, a pane or stack in the base has a “Float” destination on its own target. It floats the pane or stack in place, 10 pixels down and right of where it was. A floating pane’s destinations include the base panes, which dock it, and the panes of other windows. A Panes.MoveTrigger with target="float" moves the window’s pane or stack.
{#if state.isFloating} <Panes.MoveTrigger target="float">Move window</Panes.MoveTrigger>{/if}The arrow keys in move mode stay within one layer, which is the base or one window. F6 moves to the next layer, the base first and then each window, and Shift+F6 moves back. On a Mac laptop, F6 needs the Fn key.
The status region announces “Floated Camera.” and “Docked Camera left of Map.”, with the placement, as it does for other move-mode messages.
A few more things keep a page with windows accessible:
- Give every pane a label through
paneLabel. A window’s name comes from the labels of its panes, and an unlabeled pane leaves the window unnamed. - A window clips at its edges. Give a focusable control that sits flush against an edge an inset focus outline, or the edge hides it.
- Place windows so they do not cover a focusable base control entirely when the page loads.
- The arrow keys move a window only while the window itself has focus. A screen reader in browse mode may keep those keys for itself, so the buttons in the next section matter there too.
Moving and resizing without dragging
Section titled “Moving and resizing without dragging”WCAG 2.5.7 (Dragging Movements) asks that everything a drag does can also be done with single clicks. Arrow keys do not count, since they are not a pointer. The package draws no window frame, so this click path is yours to render: buttons that move and resize a window, as in the example. setFloatRect takes an updater, (rect) => rect, for those buttons.
{#snippet pane(node, state)} <header> <h2>{node.data.label}</h2> {#if state.isFloating} <button onclick={() => (layout = setFloatRect(layout, state.floatEntryId!, (rect) => ({ ...rect, width: rect.width + 40, })))} > Wider </button> {/if} </header>{/snippet}Render the same for each direction you need. Make each button at least 24 by 24 pixels. Those buttons are also what exempts the 8-pixel resize handles from WCAG 2.5.8 (Target Size).
Closing a window
Section titled “Closing a window”A pane in a window reads state.isFloating and state.floatEntryId, so it can offer a close button that calls removeFloat, as the example does.
{#snippet pane(node, state)} <header> <h2>{node.data.label}</h2> {#if state.isFloating} <button aria-label="Close {node.data.label}" onclick={() => (layout = removeFloat(layout, state.floatEntryId!))} > Close </button> {/if} </header>{/snippet}removePane also closes a window when it removes the window’s only pane. The pane’s wrapper carries data-floating while it is in a window, so styling can use in-data-floating: without script.
Nesting views
Section titled “Nesting views”A Panes can render inside a pane of another Panes. A component that owns its own panes, such as a visualizer with tool panels, can then sit in an app’s layout. Each view owns its own bind:layout, and the two stay independent. In the example, the outer pane’s Panes.DragTrigger wraps the whole inner view, and dragging inside the inner view still rearranges only the inner panes.
Code
<script lang="ts"> import type { LayoutNode } from "@viamrobotics/prime-panes";
import { Panes } from "@viamrobotics/prime-panes";
interface AppPane { title: string; isVisualizer?: true; }
interface ToolPane { title: string; }
let outer = $state<LayoutNode<AppPane> | undefined>({ type: "split", id: "app", direction: "row", ratio: 0.35, first: { type: "pane", id: "notes", data: { title: "Notes" } }, second: { type: "pane", id: "visualizer", data: { title: "Visualizer", isVisualizer: true }, }, });
let inner = $state<LayoutNode<ToolPane> | undefined>({ type: "split", id: "tools", direction: "column", ratio: 0.6, first: { type: "pane", id: "scene", data: { title: "Scene" } }, second: { type: "pane", id: "inspector", data: { title: "Inspector" } }, });</script>
<Panes bind:layout={outer} paneLabel={(node) => node.data.title} class="h-full"> {#snippet pane(node)} <Panes.DragTrigger> <div class="flex size-full flex-col border border-light bg-white"> <header class="flex cursor-grab items-center gap-2 border-b border-light bg-light px-2 py-1 text-xs font-semibold text-default" > {node.data.title} <Panes.MoveTrigger aria-label="Move {node.data.title}" class="button ml-auto px-2 py-0.5 text-xs font-normal" > Move </Panes.MoveTrigger> </header>
{#if node.data.isVisualizer} <Panes bind:layout={inner} paneLabel={(tool) => tool.data.title} class="min-h-0 flex-1" > {#snippet pane(tool)} <div class="flex size-full flex-col border border-light bg-white"> <Panes.DragTrigger> <header class="flex cursor-grab items-center gap-2 border-b border-light bg-light px-2 py-1 text-xs text-default" > {tool.data.title} <Panes.MoveTrigger aria-label="Move {tool.data.title}" class="button ml-auto px-2 py-0.5 text-xs" > Move </Panes.MoveTrigger> </header> </Panes.DragTrigger> </div> {/snippet} </Panes> {/if} </div> </Panes.DragTrigger> {/snippet}</Panes>- A press or a drag that starts inside the inner view never drags the outer pane around it, even when that pane’s
Panes.DragTriggerwraps the whole inner view. - Focus moving into the inner view counts as leaving the outer view. Outer move mode ends, as it does when focus leaves the page.
- Keys pressed inside the inner view, such as Escape and the move-mode arrows, act on the inner view only.
- Each view announces its own moves in its own status region.
The inner view does not stop events from propagating. Your own listeners on the outer view, including its onkeydown, onfocusout, and onpointerdown, still receive every event. Pane ids need to be unique only within one view. A pane cannot move from one view to the other.
States
Section titled “States”Each frame is a live view. The empty view renders its empty snippet. The stacked view shows its active pane under a tab strip. The floated view draws a window over its base pane. In the move-mode view, activate a grip to start move mode, which turns every other pane into a destination.
Empty
Stacked
Camera B
Floated
Map
Camera
Move mode
Camera
Stats
Activate a grip, then choose a destination. Escape cancels.
Styling
Section titled “Styling”Panes sets no size, display, or color of its own. Every part that renders an element takes class on that element:
| Part | class lands on |
|---|---|
Panes |
The root div. Size it here, or it collapses to nothing. |
Panes.TabList |
The container div. Tabs inherit its text size. |
Panes.TabListDropRegion |
The inert region. Size and position it here. |
Panes.PaneBody |
The body div. |
Panes.MoveTrigger |
The button. With a child snippet, spread props on your own element instead. |
Panes.DragTrigger renders a display: contents wrapper and takes no class. Style the elements inside it.
Three snippets replace markup the library would otherwise draw: dragPreview replaces the ghost’s content, tab on Panes.TabList replaces a tab’s content, and child on Panes.MoveTrigger replaces the button. A pane’s wrapper shows a blue focus outline, and the same outline while a press has armed the pane to drag.
The package sets these data attributes, so Tailwind variants like in-data-stacked:hidden and in-data-dragging:block work without a wrapper or script.
| Element | Attribute | Value |
|---|---|---|
Panes root |
data-move-mode |
present while move mode is active |
Panes root |
data-dragging |
present while a drag that can drop onto panes is active |
| Pane wrapper | data-stacked |
present when the pane shares its slot with other panes |
| Pane wrapper | data-floating |
present when the pane is inside a float entry |
| Pane wrapper | data-moving |
present when the pane, or its stack, is being moved in move mode |
| Pane wrapper | data-drag-armed |
present when a press has armed the pane to drag |
| Tab | aria-selected |
true on the shown tab |
Panes.MoveTrigger |
aria-pressed |
true while the pane or stack it moves is moving. Set on a button or a role="button" element |
Panes.TabListDropRegion |
data-tab-list-drop-region |
present, to select the region |
| Drag ghost | data-form |
tab or pane, what a drop would make |
| Resize handle | data-float-resize |
the axis: n, e, s, w, ne, nw, se, or sw |
The pane wrapper is the element that PaneState mirrors, so data-stacked matches isStacked, data-moving matches isMoving, and so on. The package sets other data- attributes on its drop indicators, move destinations, tabs, and window containers for its own bookkeeping. They are not part of the contract and may change.
Keyboard
Section titled “Keyboard”With focus on a divider:
| Key | Action |
|---|---|
| ArrowLeft / ArrowRight | In a row split, moves the divider 1% toward the first or second pane. |
| ArrowUp / ArrowDown | In a column split, moves the divider 1% toward the first or second pane. |
| Shift + an arrow key | Moves the divider 10%. |
| Home / End | Moves the divider as far toward the first or second pane as their minimum sizes allow. |
With focus on a Panes.MoveTrigger:
| Key | Action |
|---|---|
| Enter / Space | Enters move mode, or leaves it when it is active. |
A native button toggles through its own click. An element with role="button" toggles on Enter keydown and Space keyup, and an element with role="menuitem" through the click that its menu dispatches.
During move mode, with focus on the moving pane’s trigger:
| Key | Action |
|---|---|
| Arrow keys | Step between the sides of a pane, then cross into the adjacent pane. Arrows in a text field stay with it. |
| Tab / Shift + Tab | Moves between destinations. Each destination is one Tab stop. |
| Enter / Space | Places the pane at the focused destination. |
| F6 / Shift + F6 | Moves to the next or previous layer: the base, then each window. |
| Escape | Cancels move mode. |
Escape also cancels a pointer drag.
With focus on a tab:
| Key | Action |
|---|---|
| Tab | Moves focus into the list on the active tab, then out. |
| ArrowRight | Selects and focuses the next tab. It wraps at the end. |
| ArrowLeft | Selects and focuses the previous tab. It wraps. |
| Home / End | Selects and focuses the first or last tab. |
| Alt + Shift + ArrowLeft / ArrowRight | Moves the tab one place earlier or later, while reorderable is true. |
With focus on a window itself, not on a control inside it:
| Key | Action |
|---|---|
| An arrow key | Moves the window 10 pixels. |
| Shift + an arrow key | Moves the window 100 pixels. |
| Alt + ArrowRight / ArrowDown | Grows the right or bottom edge by 10 pixels, or 100 with Shift. |
| Alt + ArrowLeft / ArrowUp | Shrinks the right or bottom edge by 10 pixels, or 100 with Shift. It stops at floatMinSize. |
| Prop | Type | Default | Description |
|---|---|---|---|
bind:layout | LayoutNode<TData> | undefined | The layout tree. Bind it to receive resizes. undefined renders empty. | |
pane | Snippet<[PaneNode<TData>, PaneState]> | Renders one pane's content. Place Panes.DragTrigger and Panes.MoveTrigger inside it
so the pane can be dragged, and moved without dragging. The second argument is the pane's
reactive PaneState. | |
empty | Snippet | Renders when layout is undefined. | |
reorderable | boolean | true | Whether panes can be rearranged, by dragging from a Panes.DragTrigger or by activating a
Panes.MoveTrigger to pick a destination. Every rearrangement is assigned to layout, so a
function binding can reject it. Resizing is unaffected. |
keepInactiveMounted | boolean | false | Whether the inactive panes of a stack stay mounted, hidden and inert, so their state, such as
a video stream or a scroll position, survives switching tabs. By default only the active pane
of a stack is mounted. |
paneLabel | (pane: PaneNode<TData>) => string | (pane) => pane.id | Names a pane for assistive technology: the destinations that appear while a pane is being
moved without dragging, and the announcements made as it moves. Defaults to the pane's id. |
dragPreview | Snippet<[DragPreview<TData>]> | Renders the content of the ghost that follows the pointer during a drag. The library positions
the ghost above the page, hides it from assistive technology, and makes it inert, so keep the
snippet free of controls. Defaults to the dragged pane's label, or a stack's labels joined. | |
floatMinSize | (entry: FloatEntry<TData>) => { width: number; height: number } | () => ({ width: 160, height: 120 }) | The smallest a floating window can be, in pixels, per window. A window resizes no smaller, and is drawn no smaller, unless the float's box is itself smaller. Defaults to 160 by 120. |
Plus everything in Omit<HTMLAttributes<HTMLDivElement>, 'children'>, spread onto the element.
Panes.DragTrigger
Makes the elements inside it start a pane drag. Wrap a grip, or a whole header, in the pane snippet of Panes. It renders a display: contents wrapper, so it does not change layout, and it takes no class. It does nothing when reorderable is false.
What a press does depends on where it lands. A press on a plain area or a Panes.MoveTrigger drags once the pointer moves 4px, and a click on a move trigger without movement still enters move mode. A press on another control (button, a, select, or [role="button"]) drags only after a 250ms hold, so a quick click still clicks. A press on a text field (input, textarea, or [contenteditable]) never drags. A tab is the exception, since it drags at once. Once a press on a control lasts 250ms, releasing it without dragging does not click the control, a move trigger included. Keyboard activation is unaffected.
Drags run on pointer events, so mouse, pen, and touch all drag. While reorderable is true, the elements directly inside the wrapper set touch-action: none, so a swipe that starts on one drags instead of scrolling. Keep scrollable content outside it.
| Prop | Type | Default | Description |
|---|---|---|---|
children | Snippet | The elements that start a drag of the pane. A press on a plain area or a
Panes.MoveTrigger drags as soon as the pointer moves a few pixels. A press on another
control drags only after a hold, and a press on a text field never drags. | |
target | DragSource['type'] | 'pane' | What the drag moves. 'pane' moves this pane alone, leaving its stack. 'stack' moves the
pane's whole stack, and acts as 'pane' on a pane that is not stacked. 'float' moves the
floating window that holds the pane, live under the pointer with no ghost, and writes its
rect once on release. It acts as 'pane' on a pane outside a float. |
Panes.MoveTrigger
Toggles move mode, the way to rearrange a pane without dragging. Activate it with a click, Enter, or Space, then choose a destination with the pointer or the arrow keys. Dragging alone fails WCAG 2.5.7 (Dragging Movements), so every pane that has a Panes.DragTrigger needs one. It does nothing when reorderable is false.
By default it renders a <button type="button"> around children, takes button attributes, and sets aria-pressed. The optional child snippet renders your own element instead. It receives { props }, which you spread on that element.
| Element | Behavior |
|---|---|
A native button |
Its own click, Enter, and Space toggle move mode. It gets aria-pressed. |
An element with role="button" |
The library adds Enter on keydown and Space on keyup. It gets aria-pressed. You supply tabindex="0" and an accessible name. |
An element with role="menuitem" |
It toggles through click, which Radix-style menus dispatch on Enter and Space. It gets no aria-pressed, and the status region announces the state. |
When move mode ends, focus returns to the trigger. If the trigger has unmounted, as with a closed menu, focus goes to the pane itself, which shows a focus outline.
<Panes.MoveTrigger> {#snippet child({ props })} <DropdownMenu.Item role="menuitem" {...props}>Move pane</DropdownMenu.Item> {/snippet}</Panes.MoveTrigger>| Prop | Type | Default | Description |
|---|---|---|---|
children | Snippet | The default button's content. | |
child | Snippet<[{ props: Record<string, unknown> }]> | Replaces the default button with your own element, such as a menu item. Spread props on it.
Use a button, an element with role="button", or a menu item whose menu dispatches click. | |
target | DragSource['type'] | 'pane' | What the move relocates. 'pane' moves this pane alone, leaving its stack. 'stack' moves the
pane's whole stack, and acts as 'pane' on a pane that is not stacked. 'float' moves what
the floating window holds, which is its pane or stack, or this pane alone when the window
holds a split. It acts as 'pane' on a pane outside a float. |
Plus everything in Omit<HTMLButtonAttributes, 'children'>, spread onto the element.
Panes.PaneBody
Marks the part of a pane below its header. Its rect sets the pane’s edge and center drop regions, and a pane without one uses the whole pane, so a header above the body reads as the top edge. In a stacked pane with a Panes.TabList it becomes the tabpanel that the tabs control, labeled by the active tab, so a screen reader announces the panel on entry and JAWS can jump from a tab to it. Elsewhere it renders a plain div.
It is optional. Without it the tabs still work and nothing claims the tabpanel role. Use it when a header holds several controls between the tabs and the content, or when the content has no heading of its own. The pane snippet is shared by every pane, so place it once there.
| Prop | Type | Default | Description |
|---|---|---|---|
children | Snippet | The pane's body, apart from the header that holds its Panes.TabList. Its rect sets the
pane's edge and center drop regions, and a pane without one uses the whole pane. In a stacked
pane with a TabList this region becomes the tab panel the TabList controls, labeled by the
active tab. Elsewhere it renders a plain div. |
Plus everything in Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'role'>, spread onto the element.
Panes.TabList
Renders the tabs of the stack that its pane belongs to. Place it in the pane snippet of Panes, usually in the header. It renders in every pane, so every pane can include it. An unstacked pane still carries the container, which holds a Panes.TabListDropRegion, but the tablist role and the tabs appear only when the pane is stacked.
Give the list a name with aria-label, since a screen reader announces it on entry. Tabs inherit the list’s text size, and the shown tab carries aria-selected for styling. Each tab shows the pane’s label from paneLabel, or the content of the tab snippet. The tabs follow the WAI-ARIA tabs pattern with automatic selection. The list has the tablist role and each tab the tab role. A tab panel is opt-in through Panes.PaneBody. A tab drags its own pane, and the empty area of the list drags the whole stack.
Panes.TabList cannot infer TData, so an unannotated tab snippet receives PaneNode<unknown>. Annotate the parameter.
{#snippet tab(item: PaneNode<PaneData>)} {item.data.label}{/snippet}
<Panes.TabList {tab} aria-label="Stacked panes" />| Prop | Type | Default | Description |
|---|---|---|---|
tab | Snippet<[PaneNode<TData>]> | One tab's content. Defaults to the pane's label from paneLabel. | |
children | Snippet | Content after the tabs. Place Panes.TabListDropRegion here, since a drop stacks onto a
pane only over one. The container renders in every pane, so an unstacked pane has its region
too. Only a stacked pane renders the tabs and the tablist role. |
Plus everything in Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'role'>, spread onto the element.
Panes.TabListDropRegion
Marks where a dragged pane stacks onto this one. Place it inside Panes.TabList. A pane without one never stacks. It renders an aria-hidden, inert div with pointer-events-none, so only its rect matters and it never blocks the tabs under it. Size and position it with class. The pane’s wrapper is the positioned ancestor.
Three placements work: a visible strip over the tabs, a grip area, and an edge strip that shows only during a drag. A region shown only during a drag should also show in move mode, so move mode can stack there. The root’s data-dragging and data-move-mode attributes drive the styles. The first hit test after a drag starts misses a region that was hidden before, and the next pointer move finds it.
<Panes.TabList aria-label="Stacked panes" class="flex gap-1"> <Panes.TabListDropRegion class="absolute inset-x-0 top-0 hidden h-4 in-data-dragging:block in-data-move-mode:block" /></Panes.TabList>Takes className, ...rest }: Props as its props.
Layout types
Section titled “Layout types”The layout types are exported from the package root. They are types only, so they carry no runtime code.
| Type | Describes |
|---|---|
LayoutNode<TData> |
A layout tree, or any subtree of one. Narrow it on type. |
SplitNode<TData> |
A split. See The layout model. |
PaneNode<TData> |
A pane, the leaf that holds your data. See The layout model. |
StackNode<TData> |
A stack. See The stack node. |
FloatNode<TData> |
A float. See The float node. |
FloatEntry<TData> |
One window of a float node: an id, a rect, and the content it holds. |
FloatRect |
A window’s x, y, width, and height in pixels, relative to its float node’s box. |
SplitDirection |
'row' or 'column', named after CSS flex-direction. |
SplitKey |
'first' or 'second', the child slot of a split that a node occupies. |
PaneState |
The pane snippet’s second argument. See The pane snippet. |
DragPreview<TData> |
The argument of the dragPreview snippet. See The drag preview. |
Tree operations
Section titled “Tree operations”The operations behind the drops are exported, so your own controls can change the layout the same way. Each one is a pure function that takes the root and returns a new root. None of them mutates its input.
| Function | Does |
|---|---|
setSplitRatio(root, splitId, ratio) |
Sets one split’s ratio. |
swapPanes(root, firstId, secondId) |
Exchanges two panes. Each split keeps its ratio, so sizes stay with the positions. |
movePane(root, paneId, targetId, direction, key, newSplitId) |
Moves a pane beside another pane. A new direction split with ratio 0.5 and id newSplitId holds both. |
addPaneToUpperRight(root, pane, newSplitId) |
Adds a pane beside the upper-right slot, in a new split with ratio 0.5 and id newSplitId. Returns pane itself when root is undefined. |
removePane(root, paneId) |
Removes a pane. Its sibling takes its parent split’s place. Returns undefined when the pane was the only node. |
updatePaneData(root, paneId, data) |
Replaces a pane’s data. It compares by reference, so a deep comparison is up to you. |
selectPane(root, paneId) |
Shows a stacked pane by making it its stack’s activeId. |
stackPanes(root, targetPaneId, sourceId, newStackId, index?) |
Stacks a pane, or every pane of a stack, with the target. sourceId names a pane or a stack. index is the position in the target’s tab order, clamped, and defaults to the end. |
reorderPane(root, paneId, index) |
Moves a stacked pane to index in its stack’s tab order. The stack’s activeId is unchanged. |
moveStack(root, stackId, targetPaneId, direction, key, newSplitId) |
Moves a whole stack beside the target’s slot, which is its stack when it is stacked. |
swapSlots(root, firstId, secondId) |
Exchanges two slots. Each id names a pane or a stack, and a stacked pane stands for its stack. |
floatPane(root, paneId, rect, newEntryId, newFloatId, hostId?) |
Moves a pane out of its slot into a new window over the host, which is the root by default. |
floatStack(root, stackId, rect, newEntryId, newFloatId, hostId?) |
Does the same for a whole stack, which becomes the window’s content. |
setFloatRect(root, entryId, rect) |
Replaces a window’s rect. rect can be an updater, (rect) => rect, that receives the current rect. |
raiseFloat(root, entryId) |
Moves a window to the top of its float node’s stacking order. |
removeFloat(root, entryId) |
Removes a window and everything in it. |
Float operations covers the last five in detail.
When an operation has nothing to change, it returns the same root reference that it received. The cases are an id that names no node, a swap of a pane with itself, and a value that is already set. Compare the result to the input with === to know whether anything changed.
const next = removePane(layout, "camera");if (next !== layout) { layout = next;}A subtree that an operation did not touch keeps its reference too, so $derived values and keyed blocks that depend on it do not rerun.
The other operations are stack-aware too.
removePanetakes a stacked pane out of its stack. When it was active, the next pane becomes active, or the previous one when it was last.movePaneplaces a pane beside the target’s stack when the target is stacked. Moving a stacked pane beside one of its own stack’s panes takes it out of that stack.swapPanesexchanges panes inside stacks too, andactiveIdstays with the position.updatePaneDataandaddPaneToUpperRighttreat a stack as one slot or find a pane inside it.
Every operation except addPaneToUpperRight returns undefined for an undefined root.
Persisting a layout
Section titled “Persisting a layout”The setter of a function binding is the place to save. This recipe saves like the app’s teleop workspaces do.
- A structural change (swap, move, add, or remove) saves immediately.
- A resize saves after a short pause, because a drag produces many changes.
- A user without write permission never saves.
To tell the two apart, compare the previous and next trees while ignoring ratio. A resize changes nothing else.
<script lang="ts"> import { Panes } from "@viamrobotics/prime-panes"; import type { LayoutNode } from "@viamrobotics/prime-panes";
interface PaneData { title: string; }
type Layout = LayoutNode<PaneData> | undefined;
interface Props { initial: Layout; canWrite: boolean; save: (layout: Layout) => void; }
const { initial, canWrite, save }: Props = $props();
let layout = $state<Layout>(initial);
let resizeTimer: ReturnType<typeof setTimeout> | undefined;
function saveAfterResize(next: Layout) { clearTimeout(resizeTimer); resizeTimer = setTimeout(() => save(next), 200); }
const withoutRatios = (tree: Layout) => JSON.stringify(tree, (key, value) => (key === "ratio" ? undefined : value));
function propose(next: Layout) { const resized = withoutRatios(layout) === withoutRatios(next); layout = next;
if (!canWrite) return;
if (resized) { saveAfterResize(next); } else { clearTimeout(resizeTimer); save(next); } }</script>
<Panes bind:layout={() => layout, propose} class="h-screen"> {#snippet pane(node)}...{/snippet}</Panes>The structural save cancels a pending resize save first, because the structural tree already holds the latest ratios. The check serializes both trees without any ratio field, so pane data has to be JSON-serializable, as it is when you store the layout. A change to pane data, such as through updatePaneData, therefore counts as structural and saves at once.
Migrating from the app’s nodes.ts
Section titled “Migrating from the app’s nodes.ts”The app stores a workspace as a protobuf WorkspaceNode tree and renders it with svelte-splitpanes. The library replaces both the helpers in nodes.ts and the recursive panes.svelte rendering. The library model has no protobuf semantics, so the conversion lives at your boundary.
Differences
Section titled “Differences”| Protobuf | Library |
|---|---|
WorkspaceNode with a nodeId and a oneof node |
LayoutNode with a type of 'split' or 'pane', and an id |
SplitDirection enum: UNSPECIFIED, COLUMN, ROW |
'row' or 'column' |
splitPercentage, where 0 means missing |
ratio, always strictly between 0 and 1 |
A split whose first or second is undefined |
Not representable. A split always has two children. |
Widget content in oneof node, such as camera or timeSeries |
data on a pane |
Function names
Section titled “Function names”nodes.ts |
@viamrobotics/prime-panes |
|---|---|
addNodeToUpperRight(workspace, node) |
addPaneToUpperRight(root, pane, newSplitId) |
removeNode(workspace, nodeId) |
removePane(root, paneId) |
swapNodes(workspace, nodeId1, nodeId2) |
swapPanes(root, firstId, secondId) |
moveNode(workspace, nodeId, targetId, direction, key) |
movePane(root, paneId, targetId, direction, key, newSplitId) |
setSplitPercentage(workspace, nodeId, percentage) |
setSplitRatio(root, splitId, ratio) |
updateNodeContent(workspace, nodeId, content) |
updatePaneData(root, paneId, data) |
The app’s format has no stack and no float. A converter must flatten each StackNode and FloatNode into its panes or reject it, because WorkspaceNode cannot hold either. The converter below rejects them.
Two differences matter when you port callers. The nodes.ts functions mutate the workspace and return it, or return undefined when nothing changed. The library functions never mutate, and they return the same root reference when nothing changed. The library also asks you for the id of any split it creates, where nodes.ts calls crypto.randomUUID() inside.
Converting between the formats
Section titled “Converting between the formats”This converter reads a protobuf tree into the library model and writes it back. Pane data is the oneof node content, so widget code keeps working with the protobuf shapes it already knows.
import { SplitDirection, type WorkspaceNode,} from "@viamrobotics/web-client/teleop/v1/teleop";import type { LayoutNode } from "@viamrobotics/prime-panes";
type WidgetNode = Exclude< WorkspaceNode["node"], { oneofKind: "split" | undefined }>;export type Layout = LayoutNode<WidgetNode> | undefined;
const DEFAULT_RATIO = 0.5;
const readRatio = (splitPercentage: number) => splitPercentage > 0 && splitPercentage < 1 ? splitPercentage : DEFAULT_RATIO;
export const fromWorkspaceNode = (node: WorkspaceNode | undefined): Layout => { if (!node) return undefined;
if (node.node.oneofKind === "split") { const { direction, splitPercentage, first, second } = node.node.split; const firstLayout = fromWorkspaceNode(first); const secondLayout = fromWorkspaceNode(second);
// A split with one child collapses to the child it has. if (!firstLayout || !secondLayout) return firstLayout ?? secondLayout;
return { type: "split", id: node.nodeId, // UNSPECIFIED reads as column. direction: direction === SplitDirection.ROW ? "row" : "column", // A stored 0 means missing. ratio: readRatio(splitPercentage), first: firstLayout, second: secondLayout, }; }
if (node.node.oneofKind === undefined) return undefined;
return { type: "pane", id: node.nodeId, data: node.node };};
export const toWorkspaceNode = (layout: NonNullable<Layout>): WorkspaceNode => { if (layout.type === "pane") { return { nodeId: layout.id, node: layout.data }; }
if (layout.type !== "split") { throw new Error(`The workspace format has no ${layout.type}.`); }
return { nodeId: layout.id, node: { oneofKind: "split", split: { direction: layout.direction === "row" ? SplitDirection.ROW : SplitDirection.COLUMN, splitPercentage: layout.ratio, first: toWorkspaceNode(layout.first), second: toWorkspaceNode(layout.second), }, }, };};Use fromWorkspaceNode(workspace.layoutRoot) to seed the bound layout. In the persistence recipe, call toWorkspaceNode inside save, and skip it when the layout is undefined. A split with a missing child collapses to the child it has, and a workspace with no layoutRoot is an empty layout. An unspecified direction on read becomes column, so the first save writes COLUMN back. That is a one-time normalization of old data.
Limitations
Section titled “Limitations”- A stack holds panes only. It cannot hold a split or another stack.
keepInactiveMountedapplies to the whole view, not to one stack.- A swipe that starts on a drag trigger, tab, or grip drags instead of scrolling while
reorderableis true. - Resizing needs a pointer drag on the divider or the separator’s arrow keys. It has no click-only path.
- Escape cancels move mode only while focus is inside the view.
- Edge buttons crowd in panes narrower than about 72px.
- Switching browser windows during move mode cancels it.
- While a divider is dragged, the cursor for the whole page is set by a stylesheet that the splitter injects. That stylesheet takes no
nonce. Under a strict Content Security Policy it is blocked, so the global resize cursor does not change during a drag. The divider itself still resizes.