useSplitter

Hook that manages resizable panel layout with keyboard navigation and pointer-based resizing.

Panel 1

Panel 2

basic-demo

Usage#

import { useSplitter } from '@primereact/headless/splitter';
 
const { rootProps, getPanelProps, getGutterProps, thumbProps } = useSplitter({
    panels: [{ minSize: 10 }, { minSize: 10 }],
    defaultSizes: [30, 70]
});
 
return (
    <div {...rootProps} style={{ display: 'flex' }}>
        <div {...getPanelProps(0)} />
        <div {...getGutterProps(0)}>
            <div {...thumbProps} />
        </div>
        <div {...getPanelProps(1)} />
    </div>
);

useSplitter manages panel sizing, drag-to-resize, keyboard resizing, and collapse behavior — see Primitive for a component-based API.

Features#

getPanelProps(index) returns spread-ready props with flex sizing and data attributes for each panel
getGutterProps(index) returns spread-ready props with ARIA separator role, keyboard handlers, and pointer event bindings
panels config defines panel constraints (minSize, maxSize, collapsible, collapsedSize) declaratively
rootProps and thumbProps provide pre-built data attributes for the container and drag handle
state.resizing indicates whether a resize operation is in progress

Behavior#

Panel Configuration#

Define panel constraints via the panels option. Each entry supports minSize, maxSize, collapsible, and collapsedSize.

const { rootProps, getPanelProps, getGutterProps, thumbProps } = useSplitter({
    panels: [{ minSize: 10, maxSize: 80 }, { minSize: 10 }],
    defaultSizes: [30, 70]
});

Default Sizes#

Set defaultSizes for uncontrolled initial panel proportions. Values are percentages that should sum to 100.

const splitter = useSplitter({
    panels: [{ minSize: 10 }, { minSize: 10 }],
    defaultSizes: [25, 75]
});

Controlled#

Pass sizes with onResize or onResizeEnd for controlled usage.

const [sizes, setSizes] = React.useState([50, 50]);
 
const splitter = useSplitter({
    panels: [{ minSize: 10 }, { minSize: 10 }],
    sizes,
    onResizeEnd: (e) => setSizes(e.sizes)
});

Orientation#

Set orientation to 'vertical' for a top-to-bottom layout. Defaults to 'horizontal'.

const splitter = useSplitter({
    panels: [{ minSize: 10 }, { minSize: 10 }],
    orientation: 'vertical'
});

Keyboard Step#

Set step to control how many percentage points the gutter moves per arrow key press. Defaults to 5.

const splitter = useSplitter({
    panels: [{ minSize: 10 }, { minSize: 10 }],
    step: 2
});

Collapsible Panels#

Set collapsible: true on a panel config and optionally collapsedSize to enable collapse when dragged below minSize.

const splitter = useSplitter({
    panels: [{ minSize: 15, collapsible: true, collapsedSize: 5 }, { minSize: 10 }],
    defaultSizes: [30, 70]
});

Disabled#

Set disabled on the hook to prevent all resize interactions, or pass disabled per gutter via getGutterProps.

const splitter = useSplitter({
    panels: [{ minSize: 10 }, { minSize: 10 }],
    disabled: true
});
 
// or per gutter
const gutterProps = getGutterProps(0, { disabled: true });

Custom Styling with Data Attributes#

[data-orientation='horizontal'][data-resizing] {
    cursor: col-resize;
    user-select: none;
}
[data-orientation='vertical'][data-resizing] {
    cursor: row-resize;
    user-select: none;
}
[data-disabled] {
    pointer-events: none;
    opacity: 0.4;
}

API#

useSplitter#

Name	Type	Default
`panels`	`useSplitterPanelConfig[]`	—
Declarative panel configuration array. When provided, the hook auto-registers panels from this config — no `registerPanel` calls needed. Each entry defines constraints for the panel at that index.
`sizes`	`number[]`	—
Controlled panel sizes as percentages (must sum to ~100). When provided, the splitter operates in controlled mode — sizes are driven by this prop and should be updated via onResize or onResizeEnd callbacks.
`defaultSizes`	`number[]`	—
Default initial panel sizes as percentages (must sum to ~100). Used for uncontrolled mode — sets the initial sizes on mount, after which internal state takes over.
`orientation`	`"horizontal"` \| `"vertical"`	`horizontal`
Orientation of the panels.
`disabled`	`boolean`	`false`
When true, disables all resize interactions.
`step`	`number`	`5`
Step factor to increment/decrement the size of the panels while pressing the arrow keys.
`onResizeStart`	`(event: useSplitterResizeEvent) => void`	—
Callback invoked when resize starts.
`onResize`	`(event: useSplitterResizeEvent) => void`	—
Callback invoked during resize with current panel sizes.
`onResizeEnd`	`(event: useSplitterResizeEvent) => void`	—
Callback invoked when resize ends.
`onCollapse`	`(event: useSplitterCollapseEvent) => void`	—
Callback invoked when a panel collapses or expands.

Accessibility#

See Splitter Primitive for WAI-ARIA compliance details and keyboard support.