Splitter

A headless, accessible splitter for building resizable panel layouts with pointer, keyboard, and nesting support.

Features

Percentage-based layout
Horizontal or vertical orientation
Pointer and keyboard resizing
Nestable panels
Controlled layout updates
Disable all separators

Installation

npm install @ariaui/splitter

Examples

Nested splitters: a vertical pair (default 40 / 60) with a horizontal split inside the second pane (50 / 50). Separators use a wide invisible hit target and a visible grip; style with className and data-[dragging].

Default

A headless, accessible splitter example.

Preview

No preview output yet.

live.tsxReady

Anatomy

tsx

import * as Splitter from "@ariaui/splitter";

export default function Example() {
  return (
    <Splitter.Root>
      <Splitter.Panel />
      <Splitter.Separator />
      <Splitter.Panel />
    </Splitter.Root>
  );
}

API Reference

Root

Splitter container. Holds Panel + Separator children, owns the layout (percentage per panel), and coordinates resizing.

Prop	Type	Default
defaultLayout*	number[]	—
orientation	'vertical' \| 'horizontal'	'vertical'
onLayoutChange	(layout: number[]) => void	—
isDisabled	boolean	false

Attribute	Values
role	'group'

Panel

Resizable region. Registers itself with Root; its size is driven by the layout array on Root.

Prop	Type	Default
defaultSize	number	—

Separator

Drag handle placed between two Panels. Handles pointer drag, keyboard resize, and collapse-on-Enter.

Prop	Type	Default
aria-label	string	—

Attribute	Values
role	'separator'
aria-orientation	'horizontal' \| 'vertical'
aria-valuenow	current size percentage of the leading Panel
aria-valuemin	0
aria-valuemax	100
data-dragging	present while the pointer drag is active

Keyboard

Shortcut	Action
`Tab`	Move focus to the next Separator in the layout.
`←`	Vertical orientation — decrease the leading panel size by 5%.
`→`	Vertical orientation — increase the leading panel size by 5%.
`↑`	Horizontal orientation — decrease the leading panel size by 5%.
`↓`	Horizontal orientation — increase the leading panel size by 5%.
`Home`	Collapse the leading panel to 0%, giving all space to the trailing panel.
`End`	Expand the leading panel to 100%, collapsing the trailing panel.
`Enter`	Toggle collapse — first press collapses to 0%, second press restores the previous size.

Accessibility

Splitter follows the WAI-ARIA Window Splitter pattern:

Root renders with role="group" so assistive tech announces the panels + separators as a single resizable unit.
Separator renders with role="separator", aria-orientation, and live aria-valuenow / aria-valuemin / aria-valuemax reflecting the leading panel's current size as a percentage.
Separators are focusable (tabindex="0") and reachable with Tab; when isDisabled is set they drop out of the tab order (tabindex="-1") and set aria-disabled.
Provide aria-label on each Separator so screen reader users know what it resizes (e.g. "Resize sidebar").
Arrow keys match orientation: ArrowLeft/ArrowRight for "vertical", ArrowUp/ArrowDown for "horizontal". Home/End jump to the min/max positions; Enter toggles collapse and restores the previous size.
During pointer drag the Separator exposes data-dragging so custom focus/visual styles can surface the active resize.