Splitter
Splits an area into panels that the user can resize by dragging the divider between them.
Usage
import { Splitter } from '@leverui/components';
<Splitter.Root>
<Splitter.Panel />
<Splitter.ResizeTrigger>
<Splitter.ResizeTriggerSeparator />
<Splitter.ResizeTriggerIndicator />
</Splitter.ResizeTrigger>
<Splitter.Panel />
</Splitter.Root>
Shortcuts
SplitterResizeTrigger
<Splitter.ResizeTrigger id="a:b" />
Same as:
<Splitter.ResizeTrigger id="a:b">
<Splitter.ResizeTriggerSeparator />
<Splitter.ResizeTriggerIndicator />
</Splitter.ResizeTrigger>
Examples
Controlled
Use onResize and size props to manage panel sizes programmatically.
Panel A: 50.0% | Panel B: 50.0%<Splitter.Root
panels={[{ id: 'a' }, { id: 'b' }]}
size={sizes()}
onResize={(details) => setSizes(details.size)}
>
{/* ... */}
</Splitter.Root>
Store
An alternative way to control the splitter is to use the RootProvider component and the useSplitter store hook. This way you can access the splitter state and methods from outside the splitter.
Size: "50.0%, 50.0"Vertical
Pass the orientation="vertical" prop to the Splitter.Root component for stacked panels that resize vertically.
Responsive Orientation
Use the useBreakpointValue hook to change the splitter orientation based on screen size. This example shows a vertical splitter on mobile devices and a horizontal splitter on larger screens.
Multiple Panels
Create layouts with more than two resizable panels by passing an array of panels to the panels prop of the Splitter.Root component.
Collapsible Panels
Make the panels collapsible and snapped to a specific size by setting the collapsible and collapsedSize properties on a panel in the panels array. This allows users to snap panels to a defined minimum size.
<Splitter.Root
defaultSize={[40, 60]}
panels={[
{ id: 'a', collapsible: true, collapsedSize: 5, minSize: 25 },
{ id: 'b', minSize: 50 },
]}
>
{/* ... */}
</Splitter.Root>
Min/Max Constraints
Set minSize and maxSize on panels to constrain their resizable range and prevent resizing beyond these boundaries.
CSS Unit Sizes
In addition to percentages, defaultSize, minSize, and maxSize accept CSS units like px, em, rem, vh, and vw. This is useful for panels that should keep a fixed width, such as a navigation sidebar.
CSS-unit sizes are measured on the client, so panels using them can shift after hydration. Use percentage sizes for a stable server-rendered layout.
Resize Behavior
Set resizeBehavior on a panel to control how it reacts when the parent group resizes. Use "preserve-pixel-size" to keep a panel's pixel size constant (so the other panels absorb the change) instead of scaling proportionally.
Nested Panels
Here's an example of how to nest splitters inside panels to create more complex layouts. Each nested splitter can have its own orientation, sizes, and behaviors independent of the parent splitter.
Storage
Set a defaultSize and pair it with a storage solution, such as localStorage, to save users' panel size preferences. This ensures that panel layouts persist across sessions. Alternatively, you can use cookies or other storage mechanisms depending on your needs.
Disabled Resize
Pass the disabled prop to the Splitter.ResizeTrigger to disable resize on a panel. This is useful if you want certain panels to remain fixed while allowing others to resize.
<Splitter.ResizeTrigger disabled id="a:b" />
Separator Only
Customize the resize trigger to show only the separator without the indicator. This creates a minimal, clean appearance while maintaining full resize functionality.
<Splitter.ResizeTrigger id="a:b">
<Splitter.ResizeTriggerSeparator />
</Splitter.ResizeTrigger>
Reset on Double Click
Use Splitter.Context to access the splitter context and add a double-click handler to the resize trigger. This example resets panel sizes to their default values when the resize handle is double-clicked.
Resize Events
Track resize events using onResizeStart, onResize, and onResizeEnd props. This example logs all resize events with timestamps and panel sizes, useful for debugging or implementing custom resize behavior.
Keyboard Resize
The Splitter supports keyboard-based resizing for accessibility and precise control:
- Press Tab until the resize handle is focused.
- Use Arrow keys to resize panels.
- Hold Shift for larger steps.
- Press Home / End to jump to minimum or maximum sizes.
- Control the step size using the
keyboardResizeByprop.
Conditional Rendering
This example shows a horizontal splitter where panels can be shown or hidden dynamically. Use the buttons above the splitter to toggle the left and right panels - perfect for layouts where certain sections may not always be needed. The splitter automatically adjusts the remaining panels when one is hidden, keeping everything responsive. Initial panel sizes are set with defaultSize, and minSize ensures panels never shrink too small.
Dynamic Panels
Add or remove panels dynamically while maintaining relative proportions. This example demonstrates how to manage panel state and redistribute sizes when panels are added or removed.
Composition
A real-world VS Code-like layout demonstrating nested splitters with different orientations, collapsible panels, and integrated code editing.
Guides
Splitter Context
Read the context to control the splitter from code. Splitter.Context and
useSplitterContext both give a Solid accessor. Call it to read the context.
Splitter.Context Render Prop
<Splitter.Root defaultSize={[50, 50]} panels={[{ id: 'a' }, { id: 'b' }]}>
<Splitter.Panel id="a">Panel A</Splitter.Panel>
<Splitter.Context>
{(context) => <Splitter.ResizeTrigger id="a:b" onDblClick={() => context().resetSizes()} />}
</Splitter.Context>
<Splitter.Panel id="b">Panel B</Splitter.Panel>
</Splitter.Root>
useSplitterContext Hook
import { Splitter, useSplitterContext } from '@leverui/components';
function ResetButton() {
const splitter = useSplitterContext();
return <button onClick={() => splitter().resetSizes()}>Reset Sizes</button>;
}
export function Demo() {
return (
<Splitter.Root defaultSize={[50, 50]} panels={[{ id: 'a' }, { id: 'b' }]}>
<Splitter.Panel id="a">Panel A</Splitter.Panel>
<Splitter.ResizeTrigger id="a:b" />
<Splitter.Panel id="b">
<ResetButton />
</Splitter.Panel>
</Splitter.Root>
);
}
Context methods:
resetSizes(): Put every panel back to its default size.setSizes(sizes): Set the panel sizes.collapsePanel(id): Collapse the panel with that id.expandPanel(id): Expand a collapsed panel.isPanelCollapsed(id): Whether a panel is collapsed.getItems(): Current items: the panels and the handles.getSizes(): Current panel sizes, as an array.
Panels and handles
Each panel id must match an entry in panels. A resize trigger's id is the
ids of the two panels next to it, joined with a colon. A number in
defaultSize is a starting size in percent. A CSS length string such as
"180px" also works.
To control the sizes, use size with onResize. Use onResizeEnd for work
that runs once a drag or keyboard resize has finished. Give panels a minimum
and a maximum size. Keep the contents of both panels reachable at the smallest
size.
Splitter.PropsProvider gives the splitters inside it reactive default props:
splitter options or HTML attributes. createSplitterRegistry lets nested
splitters work together.
Props
Root
| Prop | Default | Type | Description |
|---|---|---|---|
panels (required) | — | PanelData[] | Panels and their size limits. |
orientation | horizontal | 'horizontal' | 'vertical' | Panels side by side (horizontal) or stacked (vertical). |
as | div | Native HTML tag | HTML tag to render. |
asChild | — | Solid render function | Render your own element with the root's props. |
unstyled | false | boolean | Turn off the Lever UI styles. |
defaultSize | — | PanelSize[] | Starting panel sizes, when you do not control them. |
id | — | string | Unique id for the splitter's state machine. |
ids | — | Partial<{ root: string; resizeTrigger: (id: string) => string; label: (id: string) => string; panel: (id: string | number) => string }> | Ids for the elements in the splitter. |
keyboardResizeBy | — | number | Pixels a keyboard resize moves a panel. |
nonce | — | string | Nonce for the cursor stylesheet the splitter adds. |
onCollapse | — | (details: SplitterExpandCollapseDetails) => void | Called when a panel collapses. |
onExpand | — | (details: SplitterExpandCollapseDetails) => void | Called when a panel expands. |
onResize | — | (details: SplitterResizeDetails) => void | Called when the splitter is resized. |
onResizeEnd | — | (details: SplitterResizeEndDetails) => void | Called when a resize ends. |
onResizeStart | — | () => void | Called when a resize starts. |
registry | — | SplitterRegistryReturn | Shared registry. Lets people drag where splitters cross. |
size | — | PanelSize[] | Panel sizes, when you control them. |
Panel
| Prop | Default | Type | Description |
|---|---|---|---|
id (required) | — | string | Panel id. Must match an entry in panels. |
as | div | Native HTML tag | HTML tag to render. |
asChild | — | Solid render function | Render your own element with the panel's props. |
ResizeTrigger
| Prop | Default | Type | Description |
|---|---|---|---|
id (required) | — | ResizeTriggerId | Ids of the two panels next to the handle, joined with a colon. |
as | button | Native HTML tag | HTML tag to render. |
asChild | — | Solid render function | Render your own element with the handle's props. |
disabled | — | boolean | Turn off resizing with this handle. |
Customize with CSS
The root and every public part have a stable .leverui-splitter__* class. The
resize trigger carries attributes for its orientation and for its focus,
dragging, and disabled states. Use style to size one splitter. unstyled
turns off the Lever UI look but keeps resizing and the part classes.
.my-splitter {
--leverui-splitter-thumb-size: 12px;
--leverui-splitter-handle-size: 28px;
--leverui-splitter-border-size: 2px;
}
.my-splitter .leverui-splitter__resizeTriggerIndicator {
background: rebeccapurple;
}
Variables also include --leverui-splitter-border-color and
--leverui-splitter-thumb-color. Your own class on the trigger, the separator,
or the indicator can override its CSS.
Explorer
Click a part name to highlight it in the preview.
Component Anatomy
Hover to highlight, click to select parts