data-splitter

Add a resizable drag divider between panels with keyboard support. The lightweight attribute alternative to the full split-surface web component.

Overview

The data-splitter attribute adds a resizable drag divider between two panels. It supports horizontal and vertical orientations, keyboard navigation, and min/max constraints. This is the lightweight attribute alternative to the full <split-surface> web component.

For persistence, collapse, and triple-pane layouts, see the split-surface component page.

How It Works

Add data-splitter to a container with exactly two child elements. The init script:

  1. Injects a div.split-divider between the two children
  2. Sets role="separator" on the divider with full ARIA attributes
  3. Listens for mouse drag, touch drag, and keyboard events on the divider
  4. Calculates the split position as a percentage and applies it to the first panel's flex-basis
  5. Reads data-min and data-max from the first child for constraints
  6. Sets data-splitter-init to prevent double-binding

The container should use data-layout="sidebar" for horizontal splits or data-layout="stack" for vertical splits.

Attributes

Attribute Element Description
data-splitter Container Enables the splitter. Empty string for horizontal, "vertical" for vertical.
data-min First child Minimum size of the first panel as a percentage (default: 10).
data-max First child Maximum size of the first panel as a percentage (default: 90).
data-splitter-init Container Set automatically to prevent double-binding. Do not set manually.

Vertical Orientation

Set data-splitter="vertical" for a top/bottom split. The container needs a fixed height since vertical splits rely on the container's height to calculate proportions.

Min/Max Constraints

Add data-min and data-max to the first child element to constrain the drag range. Values are percentages. The divider stops at these boundaries during drag and keyboard navigation.

Main Content

Injected Divider

The divider is a div.split-divider injected between the two child panels with the following accessibility attributes:

  • role="separator" and tabindex="0" for keyboard focus
  • aria-orientation matching the split direction
  • aria-valuenow, aria-valuemin, aria-valuemax tracking position
  • aria-label="Resize panels" for screen readers

Keyboard Navigation

When the divider has focus, the following keyboard controls are available:

Key Action
ArrowLeft / ArrowRight Move divider by 1% (horizontal)
ArrowUp / ArrowDown Move divider by 1% (vertical)
Shift + Arrow Move divider by 10%
Home / End Move to minimum / maximum position

Events

Event Detail Description
split-surface:resize { position } Fired during drag and keyboard resize. position is the first panel's size as a percentage.

Nested Splitters

Splitters can be nested for IDE-style layouts. Combine a horizontal sidebar split with a vertical editor/terminal split.

Styling

The divider is a plain div.split-divider styled via CSS. A ::after pseudo-element provides the grip indicator. All styles are gated on [data-splitter-init] so panels display in normal flow without JavaScript.

Dynamic Elements

Splitter containers added to the DOM after page load are automatically enhanced via a MutationObserver. No manual initialization is needed.
↑