Split Panel

Two adjacent panels separated by a draggable divider that the user can reposition. Beyond a basic split, this panel supports collapsing, magnetic auto-collapse while dragging, position persistence, animated transitions, and a rich drag lifecycle.

Preview

Start

End

Show code Copy

Installation

npm install @nana-tec/ui-components

Import

import "@nana-tec/ui-components/split-panel";

Basic usage

<nana-split-panel style="height:200px;width:100%">
  <div slot="start" style="padding:1rem">Start</div>
  <div slot="end" style="padding:1rem">End</div>
</nana-split-panel>

Collapsible

Add collapsible to let a panel snap closed past a threshold.

Start

End

Show code Copy

API

Property	Type	Default	Description
position	number	50	The current position of the divider from the primary panel’s edge as a percentage 0–100. Defaults to 50% of the container’s initial size.
positionInPixels	number | undefined	—	The current position of the divider from the primary panel’s edge in pixels.
vertical	boolean	false	Draws the split panel in a vertical orientation with the start and end panels stacked.
disabled	boolean	false	Disables resizing. Note that the position may still change as a result of resizing the host element when a primary panel is set.
primary	SplitPanelPrimary | undefined	—	If no primary panel is designated, both panels resize proportionally when the host is resized. If a primary panel is designated, it maintains its size and the other panel grows or shrinks as needed.
snap	string | SplitPanelSnapFunction | undefined	—	Snap positions in pixels, percentages, or repeat() expressions (e.g. "100px 50%" or "repeat(50%) 10px"), or a function that returns a pixel position to snap to.
snapThreshold	number	12	How close the divider must be to a snap point until snapping occurs, in pixels.
collapsible	boolean	false	Allows the primary panel to be collapsed (double-click the divider, or press Enter / Space).
collapsed	boolean	false	Whether the primary panel is currently collapsed. Reflects and can be set declaratively.
collapseThreshold	number	0	When greater than 0 and collapsible, dragging the primary panel smaller than this many pixels magnetically collapses it; dragging back out past the threshold re-expands it.
storageKey	string	''	When set, the position and collapsed state persist to localStorage under this key and are restored on load.

Events

Event	Type	Description
name	CustomEvent	—
nana-reposition	CustomEvent	Emitted whenever the divider’s position changes (detail.position).
nana-reposition-start	CustomEvent	Emitted when the user starts dragging the divider.
nana-reposition-end	CustomEvent	Emitted when the user stops dragging the divider.
nana-collapse	CustomEvent	Emitted when a panel collapses.
nana-expand	CustomEvent	Emitted when a panel expands.

Slots

Slot	Description
start	Content to place in the start panel.
end	Content to place in the end panel.
divider	The divider. Useful for slotting in a custom icon that renders as a handle.

CSS Variables

Variable	Default	Description
--divider-width	4px	The width of the visible divider.
--divider-hit-area	12px	The invisible region around the divider where dragging can occur.
--min	0%	The minimum allowed size of the primary panel.
--max	100%	The maximum allowed size of the primary panel.
--transition-duration	200ms	Duration of animated collapse / expand / reset.

CSS Parts

Part	Description
panel	Both the start and end panels
start	The start panel
end	The end panel
divider	The divider that separates the start and end panels

Accessibility

• Keyboard accessible
• Screen-reader labels
• Focus-visible states
• ARIA roles and states
• WCAG 2.2 AA contrast

Related components

• Card
• Details
• Divider
• Dialog
• Drawer

Storybook

Explore Split Panel interactively Every state, prop, and edge case — with live controls — in Storybook.

View in Storybook