Splitter
newResizable panels separated by draggable handles, built on Reka UI.
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.
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.
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.
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.
Grip
grip puts a small pill with a grip icon in the middle of the handle. The default slot replaces the icon.
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.
Splitter
| Prop | Default | Type and description |
|---|---|---|
| id | — | string | nullThe group's |
| keyboardResizeBy | — | number | nullHow far an arrow key moves a handle, as a percentage of the group. 10 by default. |
| asChild | — | booleanRender the single child instead of a wrapper, merging the group's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| direction | "horizontal" | Direction$1
|
| Event | Payload and description |
|---|---|
| layout | [val: number[]]Fires with every panel's size, each in its own unit, whenever the layout changes. |
| Slot | Scope and description |
|---|---|
| default | { layout: number[]; }The panels and handles. Receives |
SplitterPanel
| Prop | Default | Type and description |
|---|---|---|
| collapsedSize | — | numberThe size of a collapsed panel. 0 by default. |
| collapsible | — | booleanLets a drag past |
| defaultSize | — | numberThe size at first, in |
| id | — | stringThe panel's |
| maxSize | — | numberThe largest the panel can grow to. |
| minSize | — | numberThe smallest the panel can be dragged to. Past it, the drag shrinks the next panel along instead. |
| order | — | numberThe panel's place in the layout, for panels that mount conditionally or out of order. |
| sizeUnit | — | "%" | "px"
|
| asChild | — | booleanRender the single child instead of a wrapper, merging the panel's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Event | Payload and description |
|---|---|
| collapse | []Fires when the panel collapses. |
| expand | []Fires when the panel expands. |
| resize | [size: number, prevSize: number | undefined]Fires with the new size and the previous one whenever the panel's size changes, and once on mount with the starting size. |
| Slot | Scope and description |
|---|---|
| default | { isCollapsed: boolean; isExpanded: boolean; collapse: () => void; expand: () => void; resize: (size: number) => void; }The content. Receives |
| Member | Type and description |
|---|---|
| collapse | () => void | undefinedCollapses the panel, if it is |
| expand | () => void | undefinedExpands a collapsed panel to the size it had before. |
| resize | (size: number) => void | undefinedSets the panel's size, in its |
| getSize | () => numberThe current size, in the panel's |
| isCollapsed | booleanWhether the panel is collapsed. |
| isExpanded | booleanWhether the panel is not collapsed. |
SplitterHandle
| Prop | Default | Type and description |
|---|---|---|
| id | — | stringThe handle's |
| hitAreaMargins | — | PointerHitAreaMarginsHow far beyond the handle a press still grabs it, in pixels: |
| tabindex | — | numberThe handle's |
| disabled | — | booleanLocks the handle; the panels beside it keep their sizes. |
| nonce | — | stringA CSP nonce for the cursor style Reka UI injects while the pointer is over a handle. |
| asChild | — | booleanRender the single child instead of a wrapper, merging the handle's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| variant | "line" | NonNullable<"line" | "gutter" | null | undefined>
|
| grip | — | booleanDraws a small pill with a grip icon in the middle of the handle. |
| Event | Payload and description |
|---|---|
| dragging | [isDragging: boolean]Fires with |
| Slot | Scope and description |
|---|---|
| default | {}Replaces the grip icon. Only rendered with |
Props
- id
string | nullThe group'sid. Set it when rendering on the server, so the panels and handles pair up the same way after hydration.- keyboardResizeBy
number | nullHow far an arrow key moves a handle, as a percentage of the group. 10 by default.- asChild
booleanRender the single child instead of a wrapper, merging the group's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.- direction
"horizontal" Direction$1horizontallays the panels out in a row and the handles resize widths;verticalstacks them and the handles resize heights.
Emits
- layout
[val: number[]]Fires with every panel's size, each in its own unit, whenever the layout changes.
Slots
- default
{ layout: number[]; }The panels and handles. Receiveslayout.
Props
- collapsedSize
numberThe size of a collapsed panel. 0 by default.- collapsible
booleanLets a drag pastmin-sizesnap the panel down tocollapsed-size.- defaultSize
numberThe size at first, insize-unit. Panels without one share what is left.- id
stringThe panel'sid. Set it when rendering on the server.- maxSize
numberThe largest the panel can grow to.- minSize
numberThe smallest the panel can be dragged to. Past it, the drag shrinks the next panel along instead.- order
numberThe panel's place in the layout, for panels that mount conditionally or out of order.- sizeUnit
"%" | "px"%of the group, the default, orpx.- asChild
booleanRender the single child instead of a wrapper, merging the panel's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Emits
- collapse
[]Fires when the panel collapses.- expand
[]Fires when the panel expands.- resize
[size: number, prevSize: number | undefined]Fires with the new size and the previous one whenever the panel's size changes, and once on mount with the starting size.
Slots
- default
{ isCollapsed: boolean; isExpanded: boolean; collapse: () => void; expand: () => void; resize: (size: number) => void; }The content. ReceivesisCollapsed,isExpanded,collapse,expandandresize.
Exposed
- collapse
() => void | undefinedCollapses the panel, if it iscollapsible.- expand
() => void | undefinedExpands a collapsed panel to the size it had before.- resize
(size: number) => void | undefinedSets the panel's size, in itssize-unit.- getSize
() => numberThe current size, in the panel'ssize-unit.- isCollapsed
booleanWhether the panel is collapsed.- isExpanded
booleanWhether the panel is not collapsed.
Props
- id
stringThe handle'sid. Set it when rendering on the server.- hitAreaMargins
PointerHitAreaMarginsHow far beyond the handle a press still grabs it, in pixels:coarsefor touch, 15 by default, andfinefor a mouse, 5 by default.- tabindex
numberThe handle'stabindex. 0 by default, so it is in the tab order.- disabled
booleanLocks the handle; the panels beside it keep their sizes.- nonce
stringA CSP nonce for the cursor style Reka UI injects while the pointer is over a handle.- asChild
booleanRender the single child instead of a wrapper, merging the handle's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.- variant
"line" NonNullable<"line" | "gutter" | null | undefined>lineis a 1px line in--border;gutteran invisible 8px gap. Both show a--primaryline while the pointer is in the hit zone or a drag is on.- grip
booleanDraws a small pill with a grip icon in the middle of the handle.
Emits
- dragging
[isDragging: boolean]Fires withtruewhen a drag starts andfalsewhen it ends.
Slots
- default
{}Replaces the grip icon. Only rendered withgrip.
Data attributes
| data-slot | Attributes | Description |
|---|---|---|
| splitter | data-orientation, data-panel-group-id | The group. Flex row or column, filling its container. |
| splitter-panel | data-panel-size, data-state, data-panel-collapsible | A panel. data-state is collapsed or expanded on a collapsible panel. |
| splitter-handle | data-variant, data-state, data-orientation, data-disabled | A 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
| Key | Action |
|---|---|
| Tab | Moves focus to the next handle. |
| ArrowLeft / ArrowRight | Moves a horizontal group's handle by keyboard-resize-by. |
| ArrowUp / ArrowDown | Moves a vertical group's handle by keyboard-resize-by. |
| Home / End | Moves the handle to the start or the end of its range. |
| F6 | Moves focus to the next handle in the group, wrapping around; with Shift, the previous one. |