# Splitter
Package: @mantine/core
Import: import { Splitter } from '@mantine/core';
Description: Resizable split pane layout

## Usage

`Splitter` is a resizable split pane layout. Double-click a handle to restore its two panes
to their default ratio, set `resetOnDoubleClick={false}` to disable it:

```tsx
import { Splitter } from '@mantine/core';

function Demo() {
  return (
    <Splitter orientation="horizontal" h={200}>
      <Splitter.Pane defaultSize={50} min={20} bg="blue">
        First pane
      </Splitter.Pane>
      <Splitter.Pane defaultSize={50} min={20} bg="teal">
        Second pane
      </Splitter.Pane>
    </Splitter>
  );
}
```


## CSS units

`defaultSize`, `min` and `max` props of `Splitter.Pane` accept numbers, percentages and CSS units:

* A number or a `%` string is a flexible size, the pane shares the leftover space with other flexible panes
* A `px` or `rem` string is a fixed size, the pane keeps it when the container is resized

`sizes` and `onSizeChange` use the unit the pane was declared with:

```tsx
import { Splitter } from '@mantine/core';

function Demo() {
  return (
    <Splitter h={200}>
      <Splitter.Pane defaultSize="240px" min="160px" max="50%" bg="blue">
        Fixed 240px sidebar
      </Splitter.Pane>
      <Splitter.Pane defaultSize={100} bg="teal">
        Flexible content
      </Splitter.Pane>
    </Splitter>
  );
}
```


## Vertical orientation

Set `orientation="vertical"` to split panes vertically:

```tsx
import { Splitter } from '@mantine/core';

function Demo() {
  return (
    <Splitter orientation="vertical" h={300}>
      <Splitter.Pane defaultSize={60} min={20} bg="blue">
        Top pane
      </Splitter.Pane>
      <Splitter.Pane defaultSize={40} min={20} bg="teal">
        Bottom pane
      </Splitter.Pane>
    </Splitter>
  );
}
```


## Collapsible panes

Set `collapsible` prop on `Splitter.Pane` to collapse the pane when it is dragged past its minimum size:

```tsx
import { useRef } from 'react';
import { Button, Group, Splitter } from '@mantine/core';
import { UseSplitterReturnValue } from '@mantine/hooks';

function Demo() {
  const splitterRef = useRef<UseSplitterReturnValue>(null);

  return (
    <>
      <Splitter splitterRef={splitterRef} h={200}>
        <Splitter.Pane defaultSize={30} min={20} collapsible bg="blue">
          Collapsible sidebar
        </Splitter.Pane>
        <Splitter.Pane defaultSize={70} min={30} bg="teal">
          Main content
        </Splitter.Pane>
      </Splitter>
      <Group mt="md">
        <Button size="xs" onClick={() => splitterRef.current?.toggleCollapse(0)}>
          Toggle sidebar
        </Button>
      </Group>
    </>
  );
}
```


## Controlled

Use `sizes` and `onSizeChange` props to control pane sizes. `sizes` must have one value
per pane, update it when you add or remove a pane:

```tsx
import { useState } from 'react';
import { Button, Group, Splitter, Text } from '@mantine/core';

function Demo() {
  const [sizes, setSizes] = useState([50, 50]);

  return (
    <>
      <Splitter sizes={sizes} onSizeChange={(next) => setSizes(next.map(Number))} h={200}>
        <Splitter.Pane defaultSize={50} min={20} bg="blue">
          Panel A ({Math.round(sizes[0])}%)
        </Splitter.Pane>
        <Splitter.Pane defaultSize={50} min={20} bg="teal">
          Panel B ({Math.round(sizes[1])}%)
        </Splitter.Pane>
      </Splitter>
      <Text size="sm" mt="sm">
        Current sizes: [{sizes.map((s) => Math.round(s)).join(', ')}]
      </Text>
      <Group mt="xs">
        <Button size="xs" onClick={() => setSizes([30, 70])}>30 / 70</Button>
        <Button size="xs" onClick={() => setSizes([50, 50])}>50 / 50</Button>
        <Button size="xs" onClick={() => setSizes([70, 30])}>70 / 30</Button>
      </Group>
    </>
  );
}
```


## Multiple panes

`Splitter` supports any number of panes. Handles are automatically rendered between panes:

```tsx
import { Splitter } from '@mantine/core';

function Demo() {
  return (
    <Splitter h={200}>
      <Splitter.Pane defaultSize={25} min={10} bg="blue">
        First
      </Splitter.Pane>
      <Splitter.Pane defaultSize={50} min={10} bg="teal">
        Second
      </Splitter.Pane>
      <Splitter.Pane defaultSize={25} min={10} bg="grape">
        Third
      </Splitter.Pane>
    </Splitter>
  );
}
```


## Nested splitters

You can nest `Splitter` components to create complex layouts:

```tsx
import { Splitter } from '@mantine/core';

function Demo() {
  return (
    <Splitter h={350}>
      <Splitter.Pane defaultSize={30} min={15} bg="blue">
        Sidebar
      </Splitter.Pane>
      <Splitter.Pane defaultSize={70} min={30}>
        <Splitter orientation="vertical" h="100%">
          <Splitter.Pane defaultSize={60} min={20} bg="teal">
            Editor
          </Splitter.Pane>
          <Splitter.Pane defaultSize={40} min={20} bg="grape">
            Terminal
          </Splitter.Pane>
        </Splitter>
      </Splitter.Pane>
    </Splitter>
  );
}
```


## Redistribute

Set `redistribute` prop to control how space is borrowed from non-adjacent panes
when the immediate neighbor has reached its min or max size:

```tsx
import { Splitter } from '@mantine/core';

function Demo() {
  return (
    <Splitter redistribute="nearest" h={200}>
      <Splitter.Pane defaultSize={25} min={10} bg="blue">
        Panel A
      </Splitter.Pane>
      <Splitter.Pane defaultSize={25} min={10} bg="teal">
        Panel B
      </Splitter.Pane>
      <Splitter.Pane defaultSize={25} min={10} bg="grape">
        Panel C
      </Splitter.Pane>
      <Splitter.Pane defaultSize={25} min={10} bg="orange">
        Panel D
      </Splitter.Pane>
    </Splitter>
  );
}
```


## Line size

Set `lineSize` prop to change the thickness of the separator line between panes:

```tsx
import { Splitter } from '@mantine/core';

function Demo() {
  return (
    <Splitter lineSize={2} h={200}>
      <Splitter.Pane defaultSize={50} min={20} bg="blue">
        First pane
      </Splitter.Pane>
      <Splitter.Pane defaultSize={50} min={20} bg="teal">
        Second pane
      </Splitter.Pane>
    </Splitter>
  );
}
```


## Without handle

Set `withHandle={false}` to hide the thumb with grip icon. The separator line
between panes is still visible and draggable:

```tsx
import { Splitter } from '@mantine/core';

function Demo() {
  return (
    <Splitter withHandle={false} h={200}>
      <Splitter.Pane defaultSize={50} min={20} bg="blue">
        First pane
      </Splitter.Pane>
      <Splitter.Pane defaultSize={50} min={20} bg="teal">
        Second pane
      </Splitter.Pane>
    </Splitter>
  );
}
```


## Handle props

Use `getHandleProps(index)` to customize individual separators, identified by their zero-based `data-index` attribute.
Set `disabled` to prevent dragging, keyboard resizing and double-click reset.
Set `withHandle` to override thumb visibility for that separator:

```tsx
import { useState } from 'react';
import { Checkbox, Splitter, Stack } from '@mantine/core';

function Demo() {
  const [locked, setLocked] = useState(true);

  return (
    <Stack>
      <Checkbox
        label="Lock first separator"
        checked={locked}
        onChange={(event) => setLocked(event.currentTarget.checked)}
      />
      <Splitter
        h={200}
        getHandleProps={(index) => ({
          disabled: index === 0 && locked,
          withHandle: index === 0 ? !locked : true,
          mod: { locked: index === 0 && locked },
          'aria-label': index === 0 ? 'Resize first pane' : 'Resize second pane',
        })}
      >
        <Splitter.Pane defaultSize={30} min={15} bg="blue" c="white" p="md">
          First pane
        </Splitter.Pane>
        <Splitter.Pane defaultSize={40} min={15} bg="teal" c="white" p="md">
          Second pane
        </Splitter.Pane>
        <Splitter.Pane defaultSize={30} min={15} bg="grape" c="white" p="md">
          Third pane
        </Splitter.Pane>
      </Splitter>
    </Stack>
  );
}
```


## Imperative API

Use `splitterRef` prop to collapse, expand and resize panes programmatically:

```tsx
import { useRef } from 'react';
import { Splitter } from '@mantine/core';
import { UseSplitterReturnValue } from '@mantine/hooks';

function Demo() {
  const splitterRef = useRef<UseSplitterReturnValue>(null);

  return (
    <>
      <button onClick={() => splitterRef.current?.collapse(0)}>
        Collapse first pane
      </button>
      <Splitter splitterRef={splitterRef}>
        <Splitter.Pane defaultSize={50} min={20} collapsible>
          First pane
        </Splitter.Pane>
        <Splitter.Pane defaultSize={50} min={20}>
          Second pane
        </Splitter.Pane>
      </Splitter>
    </>
  );
}
```

## Wrap Splitter.Pane

`Splitter.Pane` must be a direct child of `Splitter`, wrapping it in another component is not supported:

```tsx
import { Splitter } from '@mantine/core';

// This will not work – wrapped pane will not be recognized
function WillNotWork() {
  return (
    <Splitter.Pane defaultSize={50} min={20}>
      This part will not render correctly
    </Splitter.Pane>
  );
}

// Create a separate component for pane content instead
function PaneContent() {
  return <div>This will work as expected!</div>;
}

function Demo() {
  return (
    <Splitter h={200}>
      <Splitter.Pane defaultSize={50} min={20}>
        First pane
      </Splitter.Pane>
      {/* Do not wrap Splitter.Pane in another component */}
      {/* <WillNotWork /> */}
      <Splitter.Pane defaultSize={50} min={20}>
        <PaneContent />
      </Splitter.Pane>
    </Splitter>
  );
}
```

## use-splitter hook

`Splitter` is built on top of the [use-splitter](https://alpha.mantine.dev/llms/hooks-use-splitter.md) hook.
Use the hook directly when you need full control over the layout and styling.


#### Props

**Splitter props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| children | React.ReactNode | - | Splitter panes |
| getHandleProps | (index: number) => SplitterHandleProps | - | A function to pass props down to handles, called with the handle index, use it to set `aria-label` on each handle |
| handleColor | MantineColor | - | Key of `theme.colors` or any valid CSS color for the separator line |
| handleIcon | React.ReactNode | - | Custom icon displayed in the handle thumb, by default uses grip icon based on orientation |
| lineSize | string \| number | 2 | CSS value for separator line thickness between panes |
| onCollapseChange | (panelIndex: number, collapsed: boolean) => void | - | Called when a panel collapses or expands |
| onResizeEnd | (handleIndex: number, sizes: SplitterPaneSize[]) => void | - | Called when drag ends |
| onResizeStart | (handleIndex: number) => void | - | Called when drag starts |
| onSizeChange | (sizes: SplitterPaneSize[]) => void | - | Called during resize with updated sizes, each value keeps its declared unit |
| orientation | "horizontal" \| "vertical" | 'horizontal' | Layout direction |
| redistribute | "nearest" \| "equal" \| UseSplitterRedistributeFn | - | How to redistribute space when immediate neighbor is at its min/max |
| resetOnDoubleClick | boolean | true | Restore the two panes adjacent to a handle to their default ratio (preserving their combined size) when the handle is double-clicked |
| shiftStep | SplitterStep | 10 | Shift+arrow step size, a `number`/`%` is a percentage, `px`/`rem` is resolved to pixels |
| sizes | SplitterPaneSize[] | - | Controlled sizes, each value keeps the unit it was declared in (number/`%` flexible, `px`/`rem` fixed) |
| splitterRef | RefObject<UseSplitterReturnValue<any> \| null> | - | Ref to imperative splitter API (sizes, collapse, expand, etc.) |
| step | SplitterStep | 1 | Keyboard step size, a `number`/`%` is a percentage, `px`/`rem` is resolved to pixels |
| withHandle | boolean | true | Determines whether the thumb with grip icon is displayed on the handle |

**Splitter.Pane props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| children | React.ReactNode | - | Pane content |
| collapseThreshold | SplitterPaneSize | - | Size below which the pane snaps to collapsed, defaults to `min` |
| collapsible | boolean | false | Whether this pane can be collapsed |
| defaultSize | SplitterPaneSize | required | Initial size, a `number`/`%` is a flexible size (shares leftover space), `px`/`rem` is a fixed size. A bare number is treated as a percentage. |
| max | SplitterPaneSize | - | Maximum size in the same units as `defaultSize`, no limit by default |
| min | SplitterPaneSize | 0 | Minimum size in the same units as `defaultSize` |


#### Styles API

Splitter component supports Styles API. With Styles API, you can customize styles of any inner element. Follow the documentation to learn how to use CSS modules, CSS variables and inline styles to get full control over component styles.

**Splitter selectors**

| Selector | Static selector | Description |
|----------|----------------|-------------|
| root | .mantine-Splitter-root | Root element |
| pane | .mantine-Splitter-pane | Pane element (`Splitter.Pane` component) |
| handle | .mantine-Splitter-handle | Handle element between panes, contains the separator line and the thumb |
| thumb | .mantine-Splitter-thumb | Thumb element inside the handle, contains the grip icon |

**Splitter CSS variables**

| Selector | Variable | Description |
|----------|----------|-------------|
| root | --splitter-line-size | Controls the thickness of the separator line between panes |
| root | --splitter-handle-color | Controls the color of the separator line between panes |
