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

Properties

Property	Attribute	Type	Default	Description
collapsed	—	boolean	false	Whether the primary panel is currently collapsed. Reflects and can be set declaratively.
collapseThreshold	collapse-threshold	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.
collapsible	—	boolean	false	Allows the primary panel to be collapsed (double-click the divider, or press Enter / Space).
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.
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	position-in-pixels	number | undefined	—	The current position of the divider from the primary panel's edge in pixels.
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	snap-threshold	number	12	How close the divider must be to a snap point until snapping occurs, in pixels.
storageKey	storage-key	string	''	When set, the position and collapsed state persist to `localStorage` under this key and are restored on load.
vertical	—	boolean	false	Draws the split panel in a vertical orientation with the start and end panels stacked.

Events

Event	Description
name
nana-reposition	Emitted whenever the divider's position changes (`detail.position`).
nana-reposition-start	Emitted when the user starts dragging the divider.
nana-reposition-end	Emitted when the user stops dragging the divider.
nana-collapse	Emitted when a panel collapses.
nana-expand	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 parts

Part	Description
::part(panel)	Targets both the start and end panels.
::part(start)	The start panel.
::part(end)	The end panel.
::part(divider)	The divider that separates the start and end panels.

CSS custom properties

Property	Description
--divider-width	The width of the visible divider.
--divider-hit-area	The invisible region around the divider where dragging can occur.
--min	The minimum allowed size of the primary panel.
--max	The maximum allowed size of the primary panel.
--transition-duration	Duration of animated collapse / expand / reset.

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