# useSplitter
Package: @mantine/hooks
Import: import { useSplitter } from '@mantine/hooks';
## Usage
`use-splitter` hook provides resizable split-pane functionality. It handles pointer drag
on resize handles, keyboard navigation following the WAI-ARIA Window Splitter pattern,
collapsible panels and min/max constraints.
```tsx
import React from 'react';
import { DotsSixVerticalIcon } from '@phosphor-icons/react';
import { useSplitter } from '@mantine/hooks';
const colors = ['var(--mantine-color-blue-filled)', 'var(--mantine-color-teal-filled)'];
const labels = ['Panel A', 'Panel B'];
function Demo() {
const splitter = useSplitter({
panels: [
{ defaultSize: 50, min: 20 },
{ defaultSize: 50, min: 20 },
],
});
return (
{splitter.sizes.map((size, i) => (
{i > 0 && (
)}
{labels[i]} ({Math.round(size as number)}%)
))}
);
}
```
## CSS units
`defaultSize`, `min` and `max` accept CSS units. A number or `%` string is a flexible size
that shares the leftover space, a `px` or `rem` string is a fixed size that does not change
when the container is resized. Sizes are reported in the unit they were declared in:
a `'240px'` pane stays `'240px'` in `sizes` and `onSizeChange`.
```tsx
import React from 'react';
import { DotsSixVerticalIcon } from '@phosphor-icons/react';
import { SplitterPaneSize, useSplitter } from '@mantine/hooks';
const colors = ['var(--mantine-color-blue-filled)', 'var(--mantine-color-teal-filled)'];
function getPaneStyle(size: SplitterPaneSize): React.CSSProperties {
if (typeof size === 'string' && (size.endsWith('px') || size.endsWith('rem'))) {
return { flexGrow: 0, flexShrink: 1, flexBasis: size };
}
const weight = typeof size === 'number' ? size : parseFloat(size);
return { flexGrow: weight, flexShrink: 1, flexBasis: 0 };
}
function Demo() {
const splitter = useSplitter({
panels: [
{ defaultSize: '240px', min: '160px', max: '50%' },
{ defaultSize: 100 },
],
});
const labels = ['Fixed 240px sidebar', 'Flexible content'];
return (
{splitter.sizes.map((size, i) => (
{i > 0 && (
)}
{labels[i]}
))}
);
}
```
## Vertical orientation
Set `orientation: 'vertical'` to create a vertical split layout.
Keyboard navigation uses ArrowUp/ArrowDown instead of ArrowLeft/ArrowRight:
```tsx
import React from 'react';
import { DotsSixIcon } from '@phosphor-icons/react';
import { useSplitter } from '@mantine/hooks';
const colors = ['var(--mantine-color-blue-filled)', 'var(--mantine-color-teal-filled)'];
const labels = ['Panel A', 'Panel B'];
function Demo() {
const splitter = useSplitter({
panels: [
{ defaultSize: 50, min: 20 },
{ defaultSize: 50, min: 20 },
],
orientation: 'vertical',
});
return (
{splitter.sizes.map((size, i) => (
{i > 0 && (
)}
{labels[i]} ({Math.round(size as number)}%)
))}
);
}
```
## Collapsible panels
Set `collapsible: true` on a panel to allow it to collapse to zero size.
When dragged below the `collapseThreshold` (defaults to `min`), the panel
snaps to 0%. Use `collapse()`, `expand()` and `toggleCollapse()` for
programmatic control:
```tsx
import { DotsSixVerticalIcon } from '@phosphor-icons/react';
import { Button, Group } from '@mantine/core';
import { useSplitter } from '@mantine/hooks';
function Demo() {
const splitter = useSplitter({
panels: [
{ defaultSize: 30, collapsible: true, min: 15 },
{ defaultSize: 70, min: 20 },
],
});
return (
<>
{!splitter.collapsed[0] && `Panel A (${Math.round(splitter.sizes[0] as number)}%)`}
Panel B ({Math.round(splitter.sizes[1] as number)}%)
);
}
```
## Multiple panels
The hook supports any number of panels. Each handle controls the boundary
between its two adjacent panels:
```tsx
import React from 'react';
import { DotsSixVerticalIcon } from '@phosphor-icons/react';
import { useSplitter } from '@mantine/hooks';
const colors = [
'var(--mantine-color-blue-filled)',
'var(--mantine-color-teal-filled)',
'var(--mantine-color-grape-filled)',
];
const labels = ['Panel A', 'Panel B', 'Panel C'];
function Demo() {
const splitter = useSplitter({
panels: [
{ defaultSize: 25, min: 10 },
{ defaultSize: 50, min: 20 },
{ defaultSize: 25, min: 10 },
],
});
return (
{splitter.sizes.map((size, i) => (
{i > 0 && (
)}
{labels[i]} ({Math.round(size as number)}%)
))}
);
}
```
## Redistribute
By default, each handle only affects its two adjacent panels: when a neighbor panel
is at its minimum, the handle stops. Use the `redistribute` option to borrow
space from panels further away.
### Nearest
`redistribute: 'nearest'` takes space from the nearest panel in the drag direction first,
then moves to the next one if more space is needed. Drag the first handle to
the right to see it:
```tsx
import React from 'react';
import { DotsSixVerticalIcon } from '@phosphor-icons/react';
import { useSplitter } from '@mantine/hooks';
const colors = [
'var(--mantine-color-blue-filled)',
'var(--mantine-color-teal-filled)',
'var(--mantine-color-grape-filled)',
'var(--mantine-color-orange-filled)',
];
const labels = ['Panel A', 'Panel B', 'Panel C', 'Panel D'];
function Demo() {
const splitter = useSplitter({
panels: [
{ defaultSize: 25, min: 10 },
{ defaultSize: 25, min: 20 },
{ defaultSize: 25, min: 10 },
{ defaultSize: 25, min: 10 },
],
redistribute: 'nearest',
});
return (
{splitter.sizes.map((size, i) => (
{i > 0 && (
)}
{labels[i]} ({Math.round(size as number)}%)
))}
);
}
```
### Equal
`redistribute: 'equal'` takes space equally from all panels in the
drag direction, respecting the minimum size of each panel:
```tsx
import React from 'react';
import { DotsSixVerticalIcon } from '@phosphor-icons/react';
import { useSplitter } from '@mantine/hooks';
const colors = [
'var(--mantine-color-blue-filled)',
'var(--mantine-color-teal-filled)',
'var(--mantine-color-grape-filled)',
'var(--mantine-color-orange-filled)',
];
const labels = ['Panel A', 'Panel B', 'Panel C', 'Panel D'];
function Demo() {
const splitter = useSplitter({
panels: [
{ defaultSize: 25, min: 10 },
{ defaultSize: 25, min: 20 },
{ defaultSize: 25, min: 10 },
{ defaultSize: 25, min: 10 },
],
redistribute: 'equal',
});
return (
{splitter.sizes.map((size, i) => (
{i > 0 && (
)}
{labels[i]} ({Math.round(size as number)}%)
))}
);
}
```
### Custom function
Pass a function to `redistribute` to control how space is borrowed.
The function receives `{ sizes, panels, handleIndex, delta }` and must return
a new sizes array. This example always borrows from the last panel when growing
and from the first panel when shrinking:
```tsx
import { DotsSixVerticalIcon } from '@phosphor-icons/react';
import { useSplitter, UseSplitterRedistributeInput } from '@mantine/hooks';
// Custom strategy: only take from the last panel, leave others untouched
function redistributeFromLast(input: UseSplitterRedistributeInput) {
const { sizes, panels, handleIndex, delta } = input;
const result = [...sizes];
if (delta > 0) {
const lastIdx = result.length - 1;
const minLast = panels[lastIdx].min ?? 0;
const maxGrow = (panels[handleIndex].max ?? 100) - result[handleIndex];
const canTake = result[lastIdx] - minLast;
const take = Math.min(delta, maxGrow, canTake);
result[handleIndex] += take;
result[lastIdx] -= take;
} else {
const firstIdx = 0;
const minFirst = panels[firstIdx].min ?? 0;
const growIdx = handleIndex + 1;
const maxGrow = (panels[growIdx].max ?? 100) - result[growIdx];
const canTake = result[firstIdx] - minFirst;
const take = Math.min(Math.abs(delta), maxGrow, canTake);
result[growIdx] += take;
result[firstIdx] -= take;
}
return result;
}
function Demo() {
const splitter = useSplitter({
panels: [
{ defaultSize: 25, min: 10 },
{ defaultSize: 25, min: 20 },
{ defaultSize: 50, min: 10 },
],
redistribute: redistributeFromLast,
});
return (
Panel A ({Math.round(splitter.sizes[0] as number)}%)
Panel B ({Math.round(splitter.sizes[1] as number)}%)
Panel C ({Math.round(splitter.sizes[2] as number)}%)
);
}
```
## Grip only handle
The drag handle can be a small grip button instead of a full-height bar.
In this example, only the grip icon is draggable, the line between panels is not
interactive:
```tsx
import { DotsSixVerticalIcon } from '@phosphor-icons/react';
import { useSplitter } from '@mantine/hooks';
function Demo() {
const splitter = useSplitter({
panels: [
{ defaultSize: 50, min: 20 },
{ defaultSize: 50, min: 20 },
],
});
return (
Panel A ({Math.round(splitter.sizes[0] as number)}%)
Panel B ({Math.round(splitter.sizes[1] as number)}%)
);
}
```
## Nested layout
Use several `useSplitter` instances to combine horizontal and vertical splits.
Here the right side of a horizontal split contains a vertical split:
```tsx
import { DotsSixVerticalIcon, DotsSixIcon } from '@phosphor-icons/react';
import { useSplitter } from '@mantine/hooks';
function Demo() {
const horizontal = useSplitter({
panels: [
{ defaultSize: 30, min: 15 },
{ defaultSize: 70, min: 30 },
],
});
const vertical = useSplitter({
panels: [
{ defaultSize: 60, min: 20 },
{ defaultSize: 40, min: 20 },
],
orientation: 'vertical',
});
return (
Panel A ({Math.round(horizontal.sizes[0] as number)}%)
Panel B ({Math.round(vertical.sizes[0] as number)}%)
Panel C ({Math.round(vertical.sizes[1] as number)}%)
);
}
```
## Code editor layout
A collapsible file explorer sidebar, a code editor panel and a terminal:
```tsx
import { DotsSixVerticalIcon, DotsSixIcon } from '@phosphor-icons/react';
import { Code, ScrollArea, Text } from '@mantine/core';
import { useSplitter } from '@mantine/hooks';
const files = [
'src/App.tsx',
'src/index.tsx',
'src/components/Header.tsx',
'src/components/Sidebar.tsx',
'src/hooks/useAuth.ts',
'src/utils/api.ts',
'package.json',
'tsconfig.json',
];
const sampleCode = `import { useState } from 'react';
import { Header } from './components/Header';
import { Sidebar } from './components/Sidebar';
export function App() {
const [count, setCount] = useState(0);
return (
);
}
```
## Controlled mode
Pass `sizes` and `onSizeChange` to control the sizes externally.
Use `setSizes()` for programmatic updates:
```tsx
import { useState } from 'react';
import { DotsSixVerticalIcon } from '@phosphor-icons/react';
import { Button, Group, Text } from '@mantine/core';
import { useSplitter } from '@mantine/hooks';
function Demo() {
const [sizes, setSizes] = useState([50, 50]);
const splitter = useSplitter({
panels: [
{ defaultSize: 50, min: 20 },
{ defaultSize: 50, min: 20 },
],
sizes,
onSizeChange: setSizes,
});
return (
<>
Panel A ({Math.round(splitter.sizes[0] as number)}%)
Panel B ({Math.round(splitter.sizes[1] as number)}%)
Current sizes: [{sizes.map((s) => Math.round(s)).join(', ')}]
);
}
```
## Keyboard support
Handles follow the WAI-ARIA Window Splitter pattern:
* ArrowLeft/ArrowRight – resize by `step` (horizontal)
* ArrowUp/ArrowDown – resize by `step` (vertical)
* Shift + Arrow – resize by `shiftStep`
* Home – shrink the panel before the handle to its min
* End – grow the panel before the handle to its max
* Enter – toggle collapse of the smaller adjacent collapsible panel
## Touch support
The hook uses the Pointer Events API which handles both mouse and touch automatically.
Set `touch-action: none` on the handle element to prevent the browser from
interpreting touch drag as scroll:
```css
.handle {
touch-action: none;
}
```
## Definition
```tsx
/** A bare number/`%` is a flexible size, `px`/`rem` is a fixed size */
type SplitterPaneSize = number | `${number}%` | `${number}px` | `${number}rem`;
/** A bare number/`%` is a percentage of the container, `px`/`rem` is resolved to pixels */
type SplitterStep = number | `${number}%` | `${number}px` | `${number}rem`;
interface UseSplitterPanel {
/** Initial size, a `number`/`%` is flexible, `px`/`rem` is fixed. A bare number is a percentage. */
defaultSize: SplitterPaneSize;
/** Minimum size in the same units as `defaultSize`, `0` by default */
min?: SplitterPaneSize;
/** Maximum size in the same units as `defaultSize`, no limit by default */
max?: SplitterPaneSize;
/** Whether this panel can be collapsed, `false` by default */
collapsible?: boolean;
/** Size below which the panel snaps to collapsed, defaults to `min` */
collapseThreshold?: SplitterPaneSize;
}
/** Panel config resolved to numeric units (percent or pixels) */
interface UseSplitterResolvedPanel {
defaultSize: number;
min?: number;
max?: number;
collapsible?: boolean;
collapseThreshold?: number;
}
interface UseSplitterRedistributeInput {
sizes: number[];
panels: UseSplitterResolvedPanel[];
handleIndex: number;
delta: number;
}
type UseSplitterRedistributeFn = (input: UseSplitterRedistributeInput) => number[];
interface UseSplitterOptions {
/** Panel configuration array (minimum 2 panels) */
panels: UseSplitterPanel[];
/** Layout direction, `'horizontal'` by default */
orientation?: 'horizontal' | 'vertical';
/** Controlled sizes, each value keeps the unit it was declared in */
sizes?: SplitterPaneSize[];
/** Called during resize with updated sizes, each value keeps its declared unit */
onSizeChange?: (sizes: SplitterPaneSize[]) => void;
/** Called when drag starts */
onResizeStart?: (handleIndex: number) => void;
/** Called when drag ends */
onResizeEnd?: (handleIndex: number, sizes: SplitterPaneSize[]) => void;
/** Called when a panel collapses or expands */
onCollapseChange?: (panelIndex: number, collapsed: boolean) => void;
/** How to borrow space from non-adjacent panels */
redistribute?: 'nearest' | 'equal' | UseSplitterRedistributeFn;
/** Keyboard step size, a `number`/`%` is a percentage, `px`/`rem` is pixels, `1` by default */
step?: SplitterStep;
/** Shift+arrow step size, a `number`/`%` is a percentage, `px`/`rem` is pixels, `10` by default */
shiftStep?: SplitterStep;
/** Text direction for keyboard nav, `'ltr'` by default */
dir?: 'ltr' | 'rtl';
/** Enable/disable the hook, `true` by default */
enabled?: boolean;
}
interface UseSplitterReturnValue {
/** Ref callback for the container element */
ref: React.RefCallback;
/** Current panel sizes, each value keeps the unit it was declared in */
sizes: SplitterPaneSize[];
/** Whether sizes are tracked in pixels because any pane size, `min`, `max`, `step`, `shiftStep`
* or `collapseThreshold` uses a fixed `px`/`rem` unit */
pixelMode: boolean;
/** Which panels are currently collapsed */
collapsed: boolean[];
/** Index of handle being dragged, or -1 */
activeHandle: number;
/** Get props to spread on each resize handle */
getHandleProps: (input: { index: number }) => HandleProps;
/** Programmatically set sizes */
setSizes: (sizes: SplitterPaneSize[]) => void;
/** Collapse a panel */
collapse: (panelIndex: number) => void;
/** Expand a collapsed panel */
expand: (panelIndex: number) => void;
/** Toggle collapse of a panel */
toggleCollapse: (panelIndex: number) => void;
}
function useSplitter(
options: UseSplitterOptions
): UseSplitterReturnValue
```
## Exported types
`UseSplitterPanel`, `UseSplitterOptions`, `UseSplitterReturnValue`, `UseSplitterRedistributeInput`,
`UseSplitterRedistributeFn`, `UseSplitterResolvedPanel`, `SplitterPaneSize` and `SplitterStep` types
are exported from the `@mantine/hooks` package:
```tsx
import type {
SplitterPaneSize,
SplitterStep,
UseSplitterPanel,
UseSplitterOptions,
UseSplitterReturnValue,
UseSplitterRedistributeInput,
UseSplitterRedistributeFn,
UseSplitterResolvedPanel,
} from '@mantine/hooks';
```