# Splitter (/ui/components/react/splitter)


## Usage [#usage]

```tsx
import { Splitter, SplitterPanel, SplitterHandle } from '@appica/ui-react/splitter'
```

```tsx
<Splitter defaultSizes={[30, 70]} className="h-96 rounded-xl border">
  <SplitterPanel minSize={20}>Sidebar</SplitterPanel>
  <SplitterHandle grip aria-label="Resize sidebar" />
  <SplitterPanel minSize={30}>Content</SplitterPanel>
</Splitter>
```

`Splitter` lays panels out side by side (or stacked with `orientation="vertical"`) and lets readers resize them with the handle between each pair. It follows the WAI-ARIA [window splitter](https://www.w3.org/WAI/ARIA/apg/patterns/windowsplitter/) pattern:

- **`Splitter`** - the root. Holds the sizes, as percentages in DOM order: `defaultSizes` to start from, or `sizes` and `onSizesChange` to control them. Panels split evenly when you pass neither.
- **`SplitterPanel`** - one resizable region, with its own `minSize` and `maxSize`. A `collapsible` panel snaps to `collapsedSize` when dragged past half its minimum.
- **`SplitterHandle`** - the line between 2 panels. Drag it, or focus it and use the arrow keys. `grip` adds a pill that marks it as draggable.

The root fills its container (`h-full w-full`), so give it, or its parent, a height. Panels clip their content, and a long one can scroll inside a [`ScrollArea`](/ui/components/react/scroll-area).

## Examples [#examples]

### Default [#default]

2 panels with their own minimum sizes and a grip on the handle.

```tsx
import { Splitter, SplitterPanel, SplitterHandle } from '@appica/ui-react/splitter'

export default function SplitterDefault() {
  return (
    <Splitter defaultSizes={[35, 65]} className="h-64 w-full max-w-xl overflow-hidden rounded-xl border">
      <SplitterPanel minSize={20}>
        <div className="flex h-full items-center justify-center p-4 text-sm font-medium">Sidebar</div>
      </SplitterPanel>
      <SplitterHandle grip aria-label="Resize sidebar" />
      <SplitterPanel minSize={30}>
        <div className="flex h-full items-center justify-center p-4 text-sm font-medium">Content</div>
      </SplitterPanel>
    </Splitter>
  )
}
```

### Vertical [#vertical]

`orientation="vertical"` stacks the panels, and the handle moves up and down.

```tsx
import { Splitter, SplitterPanel, SplitterHandle } from '@appica/ui-react/splitter'

export default function SplitterVertical() {
  return (
    <Splitter
      orientation="vertical"
      defaultSizes={[65, 35]}
      className="h-72 w-full max-w-xl overflow-hidden rounded-xl border"
    >
      <SplitterPanel minSize={25}>
        <div className="flex h-full items-center justify-center p-4 text-sm font-medium">Editor</div>
      </SplitterPanel>
      <SplitterHandle grip aria-label="Resize terminal" />
      <SplitterPanel minSize={15}>
        <div className="bg-background-muted flex h-full items-center justify-center p-4 font-mono text-sm">
          ~/project $
        </div>
      </SplitterPanel>
    </Splitter>
  )
}
```

### Nested [#nested]

Put a `Splitter` inside a panel to build an editor-style layout. Each splitter resizes on its own axis.

```tsx
import { Splitter, SplitterPanel, SplitterHandle } from '@appica/ui-react/splitter'

export default function SplitterNested() {
  return (
    <Splitter defaultSizes={[25, 50, 25]} className="h-80 w-full max-w-2xl overflow-hidden rounded-xl border">
      <SplitterPanel minSize={15}>
        <div className="flex h-full items-center justify-center p-4 text-sm font-medium">Files</div>
      </SplitterPanel>
      <SplitterHandle aria-label="Resize files" />
      <SplitterPanel minSize={30}>
        <Splitter orientation="vertical" defaultSizes={[70, 30]}>
          <SplitterPanel minSize={30}>
            <div className="flex h-full items-center justify-center p-4 text-sm font-medium">Editor</div>
          </SplitterPanel>
          <SplitterHandle aria-label="Resize terminal" />
          <SplitterPanel minSize={15}>
            <div className="flex h-full items-center justify-center p-4 text-sm font-medium">Terminal</div>
          </SplitterPanel>
        </Splitter>
      </SplitterPanel>
      <SplitterHandle aria-label="Resize outline" />
      <SplitterPanel minSize={15}>
        <div className="flex h-full items-center justify-center p-4 text-sm font-medium">Outline</div>
      </SplitterPanel>
    </Splitter>
  )
}
```

### Collapsible [#collapsible]

A `collapsible` panel snaps shut when dragged past half its `minSize`, and Enter on the handle collapses or restores it. Control the sizes with `sizes` and `onSizesChange` to collapse it from a button too.

```tsx
'use client'

import * as React from 'react'
import { Button } from '@appica/ui-react/button'
import { Splitter, SplitterPanel, SplitterHandle } from '@appica/ui-react/splitter'
import { LayoutSidebar } from '@appica/icons-react'

const OPEN: number[] = [30, 70]
const CLOSED: number[] = [0, 100]

export default function SplitterCollapsible() {
  const [sizes, setSizes] = React.useState(OPEN)
  const collapsed = sizes[0] === 0

  return (
    <div className="flex w-full max-w-xl flex-col gap-3">
      <Button variant="outline" size="sm" className="self-start" onClick={() => setSizes(collapsed ? OPEN : CLOSED)}>
        <LayoutSidebar data-icon="start" />
        {collapsed ? 'Show sidebar' : 'Hide sidebar'}
      </Button>
      <Splitter sizes={sizes} onSizesChange={setSizes} className="h-64 overflow-hidden rounded-xl border">
        <SplitterPanel minSize={20} collapsible>
          <div className="flex h-full items-center justify-center p-4 text-sm font-medium">Sidebar</div>
        </SplitterPanel>
        <SplitterHandle grip aria-label="Resize sidebar" />
        <SplitterPanel minSize={40}>
          <div className="flex h-full items-center justify-center p-4 text-sm font-medium">Content</div>
        </SplitterPanel>
      </Splitter>
    </div>
  )
}
```

### Remember the layout [#remember-the-layout]

`onSizesCommitted` fires once a drag ends or a key press settles, so it's the place to save the layout. Read it back into `defaultSizes`. This example keeps it in local storage with [`useLocalStorage`](/ui/docs/react/use-local-storage), so a reload keeps your sizes.

```tsx
'use client'

import { Splitter, SplitterPanel, SplitterHandle } from '@appica/ui-react/splitter'
import { useLocalStorage } from '@appica/ui-react/hooks/use-local-storage'

export default function SplitterPersist() {
  const [layout, setLayout] = useLocalStorage<number[]>('splitter-demo-layout', [40, 60])

  return (
    <Splitter
      defaultSizes={layout}
      onSizesCommitted={setLayout}
      className="h-64 w-full max-w-xl overflow-hidden rounded-xl border"
    >
      <SplitterPanel minSize={20}>
        <div className="flex h-full items-center justify-center p-4 text-sm font-medium">Inbox</div>
      </SplitterPanel>
      <SplitterHandle grip aria-label="Resize inbox" />
      <SplitterPanel minSize={30}>
        <div className="flex h-full items-center justify-center p-4 text-sm font-medium">Message</div>
      </SplitterPanel>
    </Splitter>
  )
}
```

## RTL [#rtl]

Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `<html>` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior follows the same direction.

```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}
```

The first panel sits on the right, dragging follows the pointer, and the Left and Right arrow keys swap so each still moves the handle the way it points. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).


## API reference [#api-reference]

Each part forwards every remaining prop to its `<div>`. The tables below list the Appica additions and the most common props.

### Splitter [#splitter]

The root. Lays out its panels and holds their sizes.

| Prop               | Type  | Default        | Description                                                                            |
| ------------------ | -------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `orientation`      | `'horizontal' \| 'vertical'` | `'horizontal'` | Axis the panels are laid out along. Horizontal places them side by side, vertical stacks them.                                |
| `sizes`            | `number[]`                                   | -              | Panel sizes as percentages, in DOM order. Pass it to control the component.                                                   |
| `defaultSizes`     | `number[]`                                   | -              | Panel sizes on first render, as percentages in DOM order, when the component is uncontrolled. Panels split evenly without it. |
| `onSizesChange`    | `(sizes: number[]) => void`  | -              | Fires on every change, including each frame of a drag, with the sizes in DOM order.                                           |
| `onSizesCommitted` | `(sizes: number[]) => void`  | -              | Fires once a drag ends or a key press settles, with the sizes landed on.                                                      |
| `keyboardStep`     | `number`                                     | `5`            | Percentage an arrow key moves a handle by.                                                                                    |
| `children`         | `ReactNode`                                  | -              | `SplitterPanel`s with a `SplitterHandle` between each pair.                                                                   |
| `className`        | `string`                                     | -              | Extra classes, merged via `tailwind-merge`.                                                                                   |

### SplitterPanel [#splitterpanel]

One resizable region.

| Prop            | Type        | Default | Description                                                                                                                         |
| --------------- | ----------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `minSize`       | `number`    | `0`     | Smallest size the panel resizes to, as a percentage.                                                                                |
| `maxSize`       | `number`    | `100`   | Largest size the panel resizes to, as a percentage.                                                                                 |
| `collapsible`   | `boolean`   | `false` | Let the panel snap to `collapsedSize` when dragged halfway from `minSize` toward it, or with Home and Enter on the handle after it. |
| `collapsedSize` | `number`    | `0`     | Size of the panel while collapsed, as a percentage.                                                                                 |
| `id`            | `string`    | -       | The panel's id, generated when you omit it.                                                                                         |
| `children`      | `ReactNode` | -       | The panel content.                                                                                                                  |
| `className`     | `string`    | -       | Extra classes, merged via `tailwind-merge`.                                                                                         |

A collapsed panel exposes `data-collapsed`, for styling it as a rail.

### SplitterHandle [#splitterhandle]

The draggable line between 2 panels. It resizes the panel before it and the one after it.

| Prop         | Type      | Default | Description                                                          |
| ------------ | --------- | ------- | -------------------------------------------------------------------- |
| `grip`       | `boolean` | `false` | Show a pill with dots on the line, to mark it as draggable.          |
| `aria-label` | `string`  | -       | Name for the handle, e.g. `"Resize sidebar"`. Give every handle one. |
| `className`  | `string`  | -       | Extra classes, merged via `tailwind-merge`.                          |

The handle exposes `data-dragging` while it's dragged, and the root does too.

## Accessibility [#accessibility]

- Each handle is a focusable `separator` with `aria-valuenow`, `aria-valuemin` and `aria-valuemax` (the size and limits of the panel before it) and `aria-controls` pointing at that panel, following the WAI-ARIA window splitter pattern.
- **Left/Right** (or **Up/Down** when vertical) move the handle by `keyboardStep`, **Home** and **End** send the panel before it to its minimum and maximum, and **Enter** collapses or restores a `collapsible` panel. Left and Right swap in right-to-left layouts.
- Give every handle an `aria-label` that names what it resizes. There's no default, because only you know what the panels hold.
- The handle line is 1px, with a wider invisible hit area that grows on touch screens.
- Color transitions on the handle are skipped when the user prefers reduced motion.
