Splitter

Example

<div data-slean="splitter" style="--slean-split: 30">
	<nav id="splitter-files" data-slean-part="pane" aria-label="Files">…</nav>
	<div
		role="separator"
		tabindex="0"
		aria-label="Files"
		aria-controls="splitter-files"
		aria-orientation="vertical"
		aria-valuenow="30"
		aria-valuemin="15"
		aria-valuemax="60"
		data-slean-part="handle"
	></div>
	<section data-slean-part="pane" aria-label="Editor">…</section>
</div>

<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';

	// Restore the stored size on the server and in the browser alike.
	let { size = 30 }: { size?: number } = $props();
</script>

<div
	data-slean="splitter"
	style="--slean-split: {size}"
	{@attach (node) =>
		on(node, 'slean:resize', (event) => {
			size = (event as CustomEvent<SplitterResizeDetail>).detail.value;
		})}
>
	<nav id="files" data-slean-part="pane" aria-label="Files">…</nav>
	<div
		role="separator"
		tabindex="0"
		aria-label="Files"
		aria-controls="files"
		aria-orientation="vertical"
		aria-valuenow={size}
		aria-valuemin="15"
		aria-valuemax="60"
		data-slean-part="handle"
	></div>
	<section data-slean-part="pane" aria-label="Editor">…</section>
</div>

Why this implementation exists

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, 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.

Usage

Install @svelte-lean/primitives for the behavior and @svelte-lean/styles for the stylesheet. With @svelte-lean/vite the registration is injected for every static data-slean="splitter"; without it, import the register module once.

npm install @svelte-lean/primitives

pnpm add @svelte-lean/primitives

yarn add @svelte-lean/primitives

bun add @svelte-lean/primitives

import '@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

Runtime profile

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).

Accessibility contract

• The handle is a separator with a value, bounds and an orientation, named after the pane it resizes and pointing at it with aria-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.

Keyboard

Platform features

Without JavaScript

The panes render at the server's split and cannot be resized.

Server rendering

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 hydration

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.

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. The tokens it reads:

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.

Compatibility notes

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.

Examples

Stacked panes

data-slean-orientation="vertical" stacks the panes. The separator's own aria-orientation is then horizontal, and ArrowUp and ArrowDown move it. Give the root a height.

<!-- Stacked panes: give the root a height; the separator is horizontal. -->
<div data-slean="splitter" data-slean-orientation="vertical" style="--slean-split: 60; block-size: 20rem">
	<section data-slean-part="pane">…</section>
	<div role="separator" tabindex="0" aria-orientation="horizontal" aria-valuenow="60" …></div>
	<section data-slean-part="pane">…</section>
</div>

Testing

• packages/primitives/tests/splitter.test.ts Vitest: keyboard, RTL, stacked panes, collapse, a drag session and its listeners, 1000 roots
• apps/playground/tests/primitives/layout.spec.ts Playwright: the splitter and the context menu in Chrome, with axe
• packages/styles/tests static checks of the stylesheet (layers, tokens, specificity, dark parity)

Source

• packages/primitives/src/splitter/contract.md the contract in prose: semantics, keyboard, focus, ARIA, SSR, JS-disabled behavior
• packages/primitives/src/splitter/contract.ts typed constants: name, tier, base, parts, options, events
• packages/primitives/src/splitter/behavior.ts the behavior definition
• packages/primitives/src/splitter/register.ts the registration module
• packages/styles/css/splitter.css the optional stylesheet