Splitter

new

Resizable panels separated by draggable handles, built on Reka UI.

Demo
Left
Main
Right

Open Props in the corner of the example to try disabled on the first handle. A disabled handle locks the panels beside it: no drag, no keys, no highlight.

Installation

Usage

<script setup lang="ts">
import { Splitter, SplitterHandle, SplitterPanel } from '@/components/ui/splitter'
</script>

<template>
  <div class="h-64">
    <Splitter>
      <SplitterPanel :default-size="25" :min-size="15">Left</SplitterPanel>
      <SplitterHandle />
      <SplitterPanel :default-size="75" :min-size="30">Main</SplitterPanel>
    </Splitter>
  </div>
</template>

Splitter is Reka UI's splitter with kappa-ui's handle. Panels sit in a row, or in a column with direction="vertical", and each SplitterHandle between two panels drags their shared edge. Sizes are percentages of the group unless a panel sets size-unit="px".

The splitter fills its container, so the element around it has to define a height. A class on Splitter cannot: Reka UI sets the width and height inline.

Drag a handle towards a panel and it shrinks until min-size; keep going and the drag moves on to the next panel in that direction. Two panels with a min-size therefore behave like one panel pushing the other, as in the demo above.

Each handle is a role="separator" element in the tab order. Left and right, or up and down in a vertical group, move it by keyboard-resize-by, 10% by default; Home and End send it to the ends; F6 jumps to the next handle in the group.

Examples

Vertical

direction="vertical" stacks the panels; the handle becomes a horizontal line.

Vertical
Top
Bottom

Collapsible

A collapsible panel dragged below its min-size snaps to collapsed-size, 0 by default. The panel's slot receives isCollapsed, collapse and expand, so a button can do the same. Here the sidebar is sized in pixels with size-unit="px" and keeps 48px when collapsed.

Collapsible
Main

Nested

A splitter inside a panel makes a two-dimensional layout. Each group owns its handles: double-clicking the inner one leaves the outer layout alone.

Nested
Explorer
Editor
Terminal

Gutter

variant="gutter" is an invisible 8px gap instead of a line, for panels drawn as cards. It shows the same --primary line while the pointer is over it.

Gutter
Sidebar
Main

Grip

grip puts a small pill with a grip icon in the middle of the handle. The default slot replaces the icon.

Grip
Left
Right

Double-click

Double-clicking a handle returns the two panels beside it to the sizes they had at mount, from default-size or the equal share Reka UI gave them. Any other panels absorb the difference the way a drag would.

Touch target

The handle's hit zone is not its box. Reka UI listens on <body> and treats a press as a grab when it lands within hit-area-margins of the handle's rectangle: 15px on each side for touch and 5px for a mouse, so a 1px line has a 31px zone under a finger. This is why SplitterHandle has no touch-target prop like the switch: a pseudo-element would not widen the zone. To change it, pass :hit-area-margins="{ coarse: 24, fine: 5 }". Keep the mouse margin small: a press inside the zone is a grab, not a click on the panel under it.

API Reference

Every part accepts class, merged over its base classes.

Data attributes

data-slotAttributesDescription
splitterdata-orientation, data-panel-group-idThe group. Flex row or column, filling its container.
splitter-paneldata-panel-size, data-state, data-panel-collapsibleA panel. data-state is collapsed or expanded on a collapsible panel.
splitter-handledata-variant, data-state, data-orientation, data-disabledA handle with role="separator". data-state is inactive, hover while the pointer is in the hit zone, or drag.
splitter-grip—The pill drawn by grip.

Keyboard

KeyAction
TabMoves focus to the next handle.
ArrowLeft / ArrowRightMoves a horizontal group's handle by keyboard-resize-by.
ArrowUp / ArrowDownMoves a vertical group's handle by keyboard-resize-by.
Home / EndMoves the handle to the start or the end of its range.
F6Moves focus to the next handle in the group, wrapping around; with Shift, the previous one.

Changelog

  1. registry 0.6.0

    305c540 — Splitter: Splitter, SplitterPanel and SplitterHandle over Reka UI's splitter. The handle is a line or a gutter that lights up in --primary while the pointer is in its hit zone, with an optional grip; double-clicking it puts the panels beside it back to their starting sizes.