Skip to content
Nana UI

Layout & Containers

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.

View .md Download
Start
End
  • Unit 1A
  • Unit 2B
  • Unit 4B
The list takes 35%.

Install the package for a versioned dependency:

npm install @nana-tec/ui-components

Or copy the source in and own it:

npx @nana-tec/ui add split-panel --framework web-components
npx @nana-tec/ui add split-panel --framework svelte

Lands in src/lib/components/ui/split-panel/ as NanaSplitPanel.svelte, styled with Tailwind classes that resolve to the design tokens. Requires Tailwind v4.

Import the autoloader once, in your app's entry point. Every <nana-*> tag then works anywhere, and each component downloads only the first time a page uses it:

import "@nana-tec/ui-components/autoloader";
import "@nana-tec/ui-components/theme";

The second line gives every component the Nana look and the design tokens behind it. Leave it out to style the components entirely yourself.

Import a component directly when it must be ready at once: on screen at first paint, or when you call its methods straight away. The two mix freely:

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

Copied in with npx @nana-tec/ui add split-panel? Import your project's own @/lib/nana-ui/autoloader.js once instead; the CLI keeps it up to date.

<script lang="ts">
import { NanaSplitPanel } from '$lib/components/ui/split-panel';
let position = $state(40);
</script>
<NanaSplitPanel bind:position min={20} vertical>
{#snippet start()}...{/snippet}
{#snippet end()}...{/snippet}
</NanaSplitPanel>

position is the start panel’s share, in percent. Drag the divider, or focus it and use the arrow keys (Shift for ten at a time), Page Up and Page Down, Home and End. With collapsible, Enter or a double click folds the start panel away and brings it back; without it, a double click returns to where it began.

<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>

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

Start
End

min and max are percentages the primary panel must stay within. The divider stops there whether it was dragged, nudged with the arrow keys, or set directly through position.

Never below 25%
Never below 25% either

With neither set the divider travels the whole range, which is how it has always behaved.

Properties

PropertyAttributeTypeDefaultDescription
collapsedcollapsedbooleanfalseWhether the primary panel is currently collapsed. Reflects and can be set declaratively.
collapseThresholdcollapse-thresholdnumber0When 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.
collapsiblecollapsiblebooleanfalseAllows the primary panel to be collapsed (double-click the divider, or press Enter / Space).
disableddisabledbooleanfalseDisables resizing. Note that the position may still change as a result of resizing the host element when a primary panel is set.
maxmaxnumber100Largest the primary panel may become, as a percentage of the split.
minminnumber0Smallest the primary panel may become, as a percentage of the split.
positionpositionnumber50The 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.
positionInPixelsposition-in-pixelsnumber | undefined—The current position of the divider from the primary panel's edge in pixels.
primaryprimarySplitPanelPrimary | 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.
snapsnapstring | 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.
snapThresholdsnap-thresholdnumber12How close the divider must be to a snap point until snapping occurs, in pixels.
storageKeystorage-keystring''When set, the position and collapsed state persist to localStorage under this key and are restored on load.
verticalverticalbooleanfalseDraws the split panel in a vertical orientation with the start and end panels stacked.

Methods

MethodDescription
collapse(): voidCollapse the primary panel, remembering the current position so it can be restored.
expand(): voidExpand the primary panel back to its remembered position.
reset(): voidReset the divider to the position it had when first connected.
toggle(): voidToggle the collapsed state.

Events

EventDescription
nana-repositionEmitted whenever the divider's position changes (detail.position).
nana-reposition-startEmitted when the user starts dragging the divider.
nana-reposition-endEmitted when the user stops dragging the divider.
nana-collapseEmitted when a panel collapses.
nana-expandEmitted when a panel expands.

Slots

SlotDescription
startContent to place in the start panel.
endContent to place in the end panel.
dividerThe divider. Useful for slotting in a custom icon that renders as a handle.

CSS parts

PartDescription
::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

PropertyDescription
--divider-widthThe width of the visible divider.
--divider-hit-areaThe invisible region around the divider where dragging can occur.
--minThe minimum allowed size of the primary panel.
--maxThe maximum allowed size of the primary panel.
--transition-durationDuration of animated collapse / expand / reset.

NanaSplitPanel

PropTypeDefault
positionbind:number50
minnumber0
maxnumber100
verticalbooleanfalse
disabledbooleanfalse
collapsiblebooleanfalse
collapsedbind:booleanfalse
labelstring
startrequiredSnippet
endrequiredSnippet
dividerSnippet
onPositionChange(position: number) => void

Also accepts Omit<HTMLAttributes<HTMLDivElement>, 'class'>.