Primitives Layout and display
Splitter
Two panes with a handle between them that resizes them by pointer or keyboard, such as a sidebar beside an editor.
Markdown version of this page, for assistants (Markdown for AI)
On this page
The file list takes 30% of the width.
Drag the line between the panes, or focus it and use the arrow keys.
Code
<script lang="ts">
// With @svelte-lean/vite the register import is injected for the static data-slean="splitter".
import '@svelte-lean/styles/splitter.css';
import type { SplitterResizeDetail } from '@svelte-lean/primitives/splitter';
import { on } from 'svelte/events';
let size = $state(30);
</script>
<div
class="split"
data-slean="splitter"
style="--slean-split: {size}"
{@attach (node) =>
on(node, 'slean:resize', (event) => {
size = (event as CustomEvent<SplitterResizeDetail>).detail.value;
})}
>
<nav id="splitter-files" class="pane" data-slean-part="pane" aria-label="Files">
<ul>
<li>src</li>
<li>tests</li>
<li>package.json</li>
<li>README.md</li>
</ul>
</nav>
<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
<div
role="separator"
tabindex="0"
aria-label="Files"
aria-controls="splitter-files"
aria-orientation="vertical"
aria-valuenow={size}
aria-valuemin="15"
aria-valuemax="60"
data-slean-part="handle"
></div>
<section class="pane" data-slean-part="pane" aria-label="Editor">
<p>The file list takes {size}% of the width.</p>
<p>Drag the line between the panes, or focus it and use the arrow keys.</p>
</section>
</div>
<style>
.split {
block-size: 14rem;
}
.pane {
padding: var(--slean-space-4);
font-size: var(--slean-text-sm);
}
.pane p {
margin: 0 0 var(--slean-space-2);
}
.pane ul {
display: grid;
gap: var(--slean-space-2);
margin: 0;
padding: 0;
list-style: none;
}
</style>Examples
Stacked panes
SELECT name, plan FROM teams ORDER BY name;
12 rows
Code
<script lang="ts">
// With @svelte-lean/vite the register import is injected for the static data-slean="splitter".
import '@svelte-lean/styles/splitter.css';
</script>
<!-- Stacked panes: give the root a height; the separator itself is horizontal. -->
<div
class="split"
data-slean="splitter"
data-slean-orientation="vertical"
style="--slean-split: 60"
>
<section id="splitter-query" class="pane" data-slean-part="pane" aria-label="Query">
<p><code>SELECT name, plan FROM teams ORDER BY name;</code></p>
</section>
<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
<div
role="separator"
tabindex="0"
aria-label="Query"
aria-controls="splitter-query"
aria-orientation="horizontal"
aria-valuenow="60"
aria-valuemin="20"
aria-valuemax="80"
data-slean-part="handle"
></div>
<section class="pane" data-slean-part="pane" aria-label="Results">
<p>12 rows</p>
</section>
</div>
<style>
.split {
block-size: 16rem;
}
.pane {
padding: var(--slean-space-4);
font-size: var(--slean-text-sm);
}
.pane p {
margin: 0 0 var(--slean-space-2);
}
</style>Nested
Editor
Terminal
Code
<script lang="ts">
// With @svelte-lean/vite the register import is injected for the static data-slean="splitter".
import '@svelte-lean/styles/splitter.css';
</script>
<!-- A splitter inside a pane: a sidebar beside an editor stacked over a terminal. -->
<div class="split" data-slean="splitter" style="--slean-split: 25">
<nav id="splitter-sidebar" class="pane" data-slean-part="pane" aria-label="Explorer">
<p>Explorer</p>
</nav>
<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
<div
role="separator"
tabindex="0"
aria-label="Explorer"
aria-controls="splitter-sidebar"
aria-orientation="vertical"
aria-valuenow="25"
aria-valuemin="10"
aria-valuemax="50"
data-slean-part="handle"
></div>
<div
class="inner"
data-slean-part="pane"
data-slean="splitter"
data-slean-orientation="vertical"
style="--slean-split: 70"
>
<section id="splitter-editor" class="pane" data-slean-part="pane" aria-label="Code editor">
<p>Editor</p>
</section>
<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
<div
role="separator"
tabindex="0"
aria-label="Code editor"
aria-controls="splitter-editor"
aria-orientation="horizontal"
aria-valuenow="70"
aria-valuemin="30"
aria-valuemax="90"
data-slean-part="handle"
></div>
<section class="pane" data-slean-part="pane" aria-label="Terminal">
<p>Terminal</p>
</section>
</div>
</div>
<style>
.split {
block-size: 18rem;
}
/* The outer root draws the frame. */
.inner {
border: 0;
border-radius: 0;
}
.pane {
padding: var(--slean-space-4);
font-size: var(--slean-text-sm);
}
.pane p {
margin: 0 0 var(--slean-space-2);
}
</style>Stored size
Markdown
Preview
Code
<script lang="ts">
// With @svelte-lean/vite the register import is injected for the static data-slean="splitter".
import '@svelte-lean/styles/splitter.css';
import type { SplitterResizeDetail } from '@svelte-lean/primitives/splitter';
import { on } from 'svelte/events';
const KEY = 'splitter-preview-size';
let size = $state(50);
// Restore after mount; a server-rendered page would read it from a cookie instead.
$effect(() => {
const stored = Number(localStorage.getItem(KEY));
if (stored) size = stored;
});
</script>
<div
class="split"
data-slean="splitter"
data-slean-step="10"
style="--slean-split: {size}"
{@attach (node) =>
on(node, 'slean:resize', (event) => {
size = (event as CustomEvent<SplitterResizeDetail>).detail.value;
localStorage.setItem(KEY, String(size));
})}
>
<section id="splitter-source" class="pane" data-slean-part="pane" aria-label="Markdown">
<p>Markdown</p>
</section>
<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
<div
role="separator"
tabindex="0"
aria-label="Markdown"
aria-controls="splitter-source"
aria-orientation="vertical"
aria-valuenow={size}
aria-valuemin="20"
aria-valuemax="80"
data-slean-part="handle"
></div>
<section class="pane" data-slean-part="pane" aria-label="Preview">
<p>Preview</p>
</section>
</div>
<style>
.split {
block-size: 10rem;
}
.pane {
padding: var(--slean-space-4);
font-size: var(--slean-text-sm);
}
.pane p {
margin: 0 0 var(--slean-space-2);
}
</style>Usage
Install @svelte-lean/primitives and @svelte-lean/styles. With @svelte-lean/vite the behavior registers itself for every data-slean="splitter"; without it, import the register module once.
npm install @svelte-lean/primitivespnpm add @svelte-lean/primitivesyarn add @svelte-lean/primitivesbun add @svelte-lean/primitivesimport '@svelte-lean/primitives/splitter/register';import '@svelte-lean/styles/splitter.css';Render the root with --slean-split, two pane parts and the handle between them with aria-valuenow, aria-valuemin, aria-valuemax, aria-controls and a name, usually the first pane’s.
Listen to slean:resize to store the size, and render it back on the next visit through the same two attributes.
Anatomy
| Part | Element | data-slean-part | Required | Notes |
|---|---|---|---|---|
| root | <div data-slean="splitter" style="--slean-split: 30"> | – | yes | Options: data-slean-orientation (horizontal, vertical), data-slean-step (default 5). |
| pane | any element | pane | yes | Exactly two. The first is the one the value measures. |
| handle | <div role="separator" tabindex="0" aria-valuenow aria-valuemin aria-valuemax aria-controls aria-label> | handle | yes | aria-orientation="vertical" for side-by-side panes, "horizontal" for stacked ones. |
Keyboard
| Key | When | Result |
|---|---|---|
| ArrowLeft/ArrowRight | focus on the handle, panes side by side | Smaller or larger first pane by the step; swapped under dir="rtl" |
| ArrowUp/ArrowDown | focus on the handle, panes stacked | Smaller or larger first pane by the step |
| Home/End | focus on the handle | Minimum or maximum size |
| Enter | focus on the handle | Collapses the first pane to its minimum; again restores it |
Styling
splitter.css lays the root out as a grid whose first track is --slean-split percent, draws the handle as a line with a grip that appears on hover, focus and drag, and widens it for coarse pointers. data-color on the root or an ancestor colors the active handle (primary by default). The tokens it reads:
| Token | Default (light) | Applies to |
|---|---|---|
--slean-split | 50 | grid-template-columns, grid-template-rows |
--slean-space-2 | calc(var(--slean-spacing) * 2) | grid-template-columns, grid-template-rows |
--slean-border | var(--slean-neutral-6) | border, background |
--slean-radius-md | var(--slean-radius) | border-radius |
--slean-surface | oklch(100% 0 0) | background |
--slean-fg | var(--slean-neutral-12) | color |
--slean-duration-fast | 100ms | transition |
--slean-ease | cubic-bezier(0.2, 0, 0, 1) | transition |
--slean-radius-full | 9999px | border-radius |
--slean-border-strong | var(--slean-neutral-8) | background |
--slean-color-main | var(--slean-primary-main) | background |
--slean-focus-ring | var(--slean-focus-ring-width) solid var(--slean-focus-ring-color) | outline |
--slean-focus-ring-width | 2px | outline-offset |
--slean-space-5 | calc(var(--slean-spacing) * 5) | grid-template-columns, grid-template-rows |
State selectors the stylesheet targets, all from the platform or ARIA: :focus-visible, :hover, [aria-disabled="true"].
Variant attributes: data-slean-orientation (vertical); data-slean-dragging.
Under the hood
Runtime and size
- Tier
- 2 · Lazy scoped controller
- Behavior JS
- 1908 B brotli · 2132 B gzip ·
packages/· methodprimitives/ artifacts/ size.json - Platform features
role="separator",aria-valuenow,setPointerCapture(),touch-action,CSS grid- Shared listeners
- keydown, pointerdown
- Per-instance listeners
- scoped to one interaction session
- Lazy state
- WeakMap entry created on first interaction
- Native base
role="separator" (WAI-ARIA window splitter) + CSS grid
The splitter registers one keydown and one pointerdown handler with the shared router. During a drag, and only then, the handle holds four listeners and the root's box. A thousand splitters keep one listener per type (tests/splitter.test.ts).
Why this implementation
CSS resize resizes one box by a corner grip, with no keyboard and nothing for assistive technology. The WAI-ARIA window splitter is the accessible form: a focusable separator with a value, moved by the arrow keys and by the pointer.
The value is the state. aria-valuenow on the handle and --slean-split on the root carry the same number, a percentage of the root, and the stylesheet turns the property into the first grid track, so a split rendered on the server is right before the script loads. The keyboard reads and writes the attribute and keeps nothing. A drag is the one moment that needs memory: pointer capture and four listeners on the handle, created on pointerdown and removed on release. That scoped lifetime is what Tier 2 means here.
The browser owns
- focus on the handle and the keydown and pointerdown events routed to the behavior
- pointer capture: the handle keeps receiving the drag outside its own box
- the grid layout that turns one number into two panes
Svelte Lean owns
- the WAI-ARIA window splitter keyboard: arrows by a step, Home, End, Enter to collapse and restore
- a pointer drag whose listeners live exactly as long as the drag
- aria-valuenow and --slean-split kept equal, bounded by aria-valuemin and aria-valuemax
- slean:resize after every change; RTL and stacked panes
- splitter.css: the grid, the handle line and grip, focus and drag states
Accessibility
- The handle is a
separatorwith a value, bounds and an orientation, named after the pane it resizes and pointing at it witharia-controls. - Arrow keys move it by
data-slean-step; Home and End go to the bounds; Enter collapses and restores the first pane. - Under
dir="rtl"the first pane is on the right: the drag measures from the right edge and ArrowLeft enlarges it. - A drag focuses the handle, so the keyboard continues from where the pointer left it.
Platform features
| Feature | Baseline | Outside the target |
|---|---|---|
Pointer events, pointer capture | Widely available | Not applicable |
touch-action | Widely available | Not applicable |
Without JavaScript
The panes render at the server's split and cannot be resized.
Server rendering and hydration
Render the same value in aria-valuenow and in the root's --slean-split. Nothing is measured on the server. A Content Security Policy without style-src-attr 'unsafe-inline' blocks the style attribute: the panes then start at an even split until the first key or drag, since the behavior writes through the CSSOM.
Before the behavior loads, the handle is focusable but neither keys nor drags move it. The first event after hydration works on the server's markup.
Compatibility
Pointer events, pointer capture, touch-action and CSS grid are widely available. More than two panes, pixel sizes and persistence are not part of the primitive; nest splitters and store the value from slean:resize.
Tests and source
packages/primitives/tests/splitter.test.tsVitest: keyboard, RTL, stacked panes, collapse, a drag session and its listeners, 1000 rootsapps/playground/tests/primitives/layout.spec.tsPlaywright: the splitter and the context menu in Chrome, with axepackages/styles/testsstatic checks of the stylesheet (layers, tokens, specificity, dark parity)
packages/primitives/src/splitter/contract.mdthe contract in prose: semantics, keyboard, focus, ARIA, SSR, JS-disabled behaviorpackages/primitives/src/splitter/contract.tstyped constants: name, tier, base, parts, options, eventspackages/primitives/src/splitter/behavior.tsthe behavior definitionpackages/primitives/src/splitter/register.tsthe registration modulepackages/styles/css/splitter.cssthe optional stylesheet