## Overview [#overview]
Resizable creates panel layouts with draggable separators. It does not own a panel background, border, radius, or shadow; wrap it in `Card`, `Surface`, or an app-owned container when you need a framed area. The examples below use consumer-painted frame classes with `SurfaceProvider` so the resize handle reads the matching surface context.
## Usage [#usage]
```tsx
import {
ResizableHandle,
ResizablePanel,
ResizablePanelGroup,
} from "@tilt-legal/cubitt-components/resizable";
import { SurfaceProvider } from "@tilt-legal/cubitt-components/utilities";
```
```tsx
One
Two
```
## Examples [#examples]
### Vertical [#vertical]
Use `orientation="vertical"` to stack panels vertically.
```tsx
import {
ResizableHandle,
ResizablePanel,
ResizablePanelGroup,
} from "@tilt-legal/cubitt-components/resizable";
import { SurfaceProvider } from "@tilt-legal/cubitt-components/utilities";
export default function Component() {
return (
Header
Content
);
}
```
### With Handle [#with-handle]
Add `withHandle` to display a visible grip on the resize separator.
```tsx
import {
ResizableHandle,
ResizablePanel,
ResizablePanelGroup,
} from "@tilt-legal/cubitt-components/resizable";
import { SurfaceProvider } from "@tilt-legal/cubitt-components/utilities";
export default function Component() {
return (
One
Two
);
}
```
### Pixel-Based Sizing [#pixel-based-sizing]
Use numeric values for pixel-based constraints. The second panel fills the remaining space.
```tsx
import {
ResizableHandle,
ResizablePanel,
ResizablePanelGroup,
} from "@tilt-legal/cubitt-components/resizable";
import { SurfaceProvider } from "@tilt-legal/cubitt-components/utilities";
export default function Component() {
return (
Fixed Sidebar (280px)
Flexible Content
);
}
```
## API Reference [#api-reference]
### ResizablePanelGroup [#resizablepanelgroup]
Container component that manages the resizable panel layout.
| Prop | Type | Default | Description |
| ---------------- | ---------------------------- | -------------- | ----------------------------------------------------------- |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | The panel layout direction. |
| `onLayoutChange` | `(layout: Layout) => void` | - | Callback when panel sizes change. |
| `className` | `string` | - | Additional classes for layout sizing and app-owned framing. |
### ResizablePanel [#resizablepanel]
Panel size props accept percentages, pixels, relative font units, and viewport units. Numeric values are treated as pixels, while strings without units are treated as percentages.
| Prop | Type | Default | Description |
| --------------- | ------------------ | ------- | -------------------------------------------- |
| `defaultSize` | `number \| string` | - | Initial size. |
| `minSize` | `number \| string` | - | Minimum size constraint. |
| `maxSize` | `number \| string` | - | Maximum size constraint. |
| `collapsible` | `boolean` | `false` | Whether the panel can collapse. |
| `collapsedSize` | `number \| string` | - | Size when collapsed. |
| `onResize` | `(size) => void` | - | Callback when the panel is resized. |
| `className` | `string` | - | Additional classes for panel content layout. |
### ResizableHandle [#resizablehandle]
Draggable separator between panels.
| Prop | Type | Default | Description |
| ------------ | ---------------------------- | ------- | --------------------------------------------------------------------- |
| `withHandle` | `boolean \| React.ReactNode` | `false` | Shows the default grip when `true`, or renders a custom grip element. |
| `disabled` | `boolean` | `false` | Disables resizing through this handle. |
| `className` | `string` | - | Additional classes for the separator. |
## Hooks [#hooks]
### useResizablePanelRef [#useresizablepanelref]
Get a ref to imperatively control a panel.
```tsx
import { useResizablePanelRef } from "@tilt-legal/cubitt-components/resizable";
function Component() {
const panelRef = useResizablePanelRef();
return (
Sidebar
Content
);
}
```
### useResizableGroupRef [#useresizablegroupref]
Get a ref to imperatively control the entire group layout.
```tsx
import { useResizableGroupRef } from "@tilt-legal/cubitt-components/resizable";
function Component() {
const groupRef = useResizableGroupRef();
return (
Left
Right
);
}
```
### useResizableDefaultLayout [#useresizabledefaultlayout]
Persist and restore layouts to storage.
```tsx
import { useResizableDefaultLayout } from "@tilt-legal/cubitt-components/resizable";
function Component() {
const { defaultLayout } = useResizableDefaultLayout({
panelIds: ["sidebar", "content"],
storage: localStorage,
});
return (
Content
);
}
```
## Types [#types]
```tsx
import type {
ResizableLayout,
ResizablePanelGroupHandle,
ResizablePanelHandle,
ResizablePanelSize,
} from "@tilt-legal/cubitt-components/resizable";
```
## Credits [#credits]
Built with [react-resizable-panels](https://github.com/bvaughn/react-resizable-panels).