# Resizable
Resize, collapse, and save panel layouts with pointer and keyboard controls.
Use a resizable group to let people size the panes of a layout, like a file list beside an editor, by dragging the handle between them or with the keyboard.
```ts title="basic.ts"
import "@ui-sdk/web/resizable"
function mount(root: HTMLElement) {
root.innerHTML = `
Files
page.tsx
layout.tsx
globals.css
page.tsx
Saved just now
Terminal
Ready on port 3000
`
}
export { mount }
```
Drag the handle beside Files, then the one between page.tsx and Terminal.
## Installation
```bash
npm install @ui-sdk/web @ui-sdk/core
```
Importing the component defines its elements. On the server the import does nothing.
```ts
import "@ui-sdk/web/resizable"
```
## Composition
Use the following composition to build a `ui-resizable`:
```text
ui-resizable
├── ui-resizable-panel
├── ui-resizable-handle
└── ui-resizable-panel
```
Put a handle between the panels you want to resize, and name it with `aria-label`, like "Resize files". The group lays its panels out in a row, so give it a size, and each panel's size is a percentage of the space the panels share. A group can sit inside a panel, like an editor above a terminal.
## Usage
Import the parts and put them together:
```html
FilesEditor
```
The panel without `default-size` takes what's left, here 70%.
## Build Your Own
`@ui-sdk/web/resizable` comes with ready-made `ui-resizable` elements. If you'd like to build your own, with your own element names, start from the `resizable` primitive in `@ui-sdk/core`:
```ts title="split-view-elements.ts"
import { resizable } from "@ui-sdk/core/resizable"
import { createParts } from "@ui-sdk/web"
createParts(resizable, {
root: { tag: "split-view", display: "block" },
panel: { tag: "split-view-pane", display: "block" },
handle: { tag: "split-view-divider", display: "block" },
})
```
```html
FilesEditor
```
Each element keeps the behavior, state and data attributes of its ready-made counterpart: the root lays the panels out, each pane writes its size to `--resizable-panel-size`, and the divider is the focusable separator. See [Rendering](/docs/web-components/rendering) and [Custom Parts](/docs/web-components/custom-parts) for more.
## Vertical
Set `orientation="vertical"` to stack the panels, and give the group a height. ArrowUp and ArrowDown move the handle. Every part gets `data-orientation` with the group's direction, so a vertical group's handle is `[data-slot="resizable-handle"][data-orientation="vertical"]`.
```ts title="vertical.ts"
import "@ui-sdk/web/resizable"
function mount(root: HTMLElement) {
root.innerHTML = `
Inbox
3 unread messages
Quarterly report
From Hollis Grant
`
}
export { mount }
```
Drag the handle between Inbox and Quarterly report, or focus it and use ArrowUp and ArrowDown.
## Handle
Put anything inside a handle, like a grip that shows it can be dragged. The handle can stay a thin line: its hit area is at least 10 pixels across, centered on it, and 24 for touch, without any styles.
```ts title="handle.ts"
import "@ui-sdk/web/resizable"
function mount(root: HTMLElement) {
root.innerHTML = `
Channels
general
design
releases
general
Kofi Mensah: The release notes are ready.
`
}
export { mount }
```
Grab the grip beside Channels, or focus the handle and use the arrow keys.
## Collapsible
`collapsible` lets a panel collapse below its `min-size` to `collapsed-size`, 0 by default: by dragging past the midpoint to its collapsed size, with Enter or a double-click on its handle, or through the controller. Dragging back past the same point opens it at its minimum, and Enter restores the size it had. A collapsed panel gets `data-collapsed`, and at size 0 its content leaves the tab order and the accessibility tree.
```ts title="collapsible.ts"
import "@ui-sdk/web/resizable"
import { createElement, Folder, Search, Settings } from "lucide"
function mount(root: HTMLElement) {
root.innerHTML = `
Edited by Inès Moreau
`
}
export { mount }
```
Drag the sidebar closed to leave only its icons, or focus its handle and press Enter to collapse and restore it.
## Sizes in Pixels
Sizes are percentages as numbers, or strings with `%`, `px` or `rem`. Pixel and rem bounds hold as the group resizes, so a navigation with `min-size="160px"` never gets narrower, and a change they cause reports the `resize` reason.
```ts title="sizes.ts"
import "@ui-sdk/web/resizable"
function mount(root: HTMLElement) {
root.innerHTML = `
Docs
Getting Started
Components
Guides
Getting Started
Install the packages
`
}
export { mount }
```
Resize Docs. It stays between 160 and 320 pixels wide, whatever the width of the group.
## Default Layout
`default-layout` sets every panel's size at once, in order, like `"25,35,40"`. Otherwise panels without `default-size` share what's left evenly.
```ts title="default-layout.ts"
import "@ui-sdk/web/resizable"
function mount(root: HTMLElement) {
root.innerHTML = `
Mail
Inbox
Drafts
Sent
Inbox
Hollis Grant
Inès Moreau
Kofi Mensah
Quarterly report
From Hollis Grant
`
}
export { mount }
```
The three mail panels start at 25, 35 and 40 percent. Resize any of them.
## Controlled
Set the element's `layout` property, and listen for `layoutchange` for the reason. The layout is one percentage per panel, in order, adding up to 100. Every change carries a [reason](#reasons), like `drag`, `step-key` or `collapse`, and `event.preventDefault()` keeps the current layout. Setting `layout` fires `layoutchange` too, with the `imperative` reason.
```ts title="controlled.ts"
import "@ui-sdk/web/resizable"
import { log } from "./log"
const format = (layout: number[]) => layout.map(Math.round).join(" / ")
function mount(root: HTMLElement) {
root.innerHTML = `
Files
page.tsx
layout.tsx
globals.css
page.tsx
Saved just now
`
const group = root.querySelector("ui-resizable")!
let layout = [30, 70]
group.addEventListener("layoutchange", (event) => {
const { value, reason } = event.detail
if (format(value) !== format(layout)) {
log(root, `${format(value)} (${reason})`)
}
layout = value
})
root
.querySelectorAll("[data-layout]")
.forEach((button) => {
button.addEventListener(
"click",
() => (group.layout = button.dataset.layout!.split(",").map(Number))
)
})
}
export { mount }
```
Resize Files to log the layout and its reason. Split Evenly and Reset set the layout from outside.
## Saving on Complete
`layoutchange` fires on every frame of a drag. `layoutcommit` fires once, when the interaction that changed the layout ends: the pointer lifts, the key comes up, or a panel collapses. Save there.
```ts title="complete.ts"
import "@ui-sdk/web/resizable"
import { log } from "./log"
function mount(root: HTMLElement) {
root.innerHTML = `
Files
page.tsx
layout.tsx
globals.css
page.tsx
Saved just now
`
root
.querySelector("ui-resizable")!
.addEventListener("layoutcommit", (event) => {
log(
root,
`Saved ${event.detail.value.map(Math.round).join(" / ")} (${event.detail.reason})`
)
})
}
export { mount }
```
Drag the handle and release it, or press an arrow key. The console logs the layout once, when you let go.
## Persistence
`auto-save-id` saves the layout in `localStorage` when an interaction completes and restores it when the group attaches in the browser. Server markup starts with the default sizes. Each set of panels keeps its own layout, so a panel that comes and goes gets its sizes back. Give panels an `id` so the saved layout survives changes elsewhere on the page.
It's the same idea as [Preferences](/docs/web-components/components/preferences), which saves one choice between visits, like a theme. Resizable saves the whole layout, under its `auto-save-id`.
```ts title="persistence.ts"
import "@ui-sdk/web/resizable"
function mount(root: HTMLElement) {
root.innerHTML = `
Outline
Introduction
Installation
Usage
Introduction
Last edited by Wren Takahashi
`
}
export { mount }
```
Resize Outline, then reload this page to restore its saved width.
## Storage
The `storage` property takes anything with `getItem` and `setItem`, like `sessionStorage` or a cookie. That's the browser's storage shape, not the [storage](/docs/web-components/components/preferences#save-the-value) helpers Preferences takes, such as `createLocalStorage`, which each keep one value. Choose between local storage, session storage and a cookie as you would for a preference, under [Remember the Choice](/docs/core/behaviors/preferences#remember-the-choice).
This example keeps the layout in `sessionStorage`, for the tab's session. It sets `storage` before the group is in the page, so the group restores from it when it attaches:
```ts title="storage.ts"
import "@ui-sdk/web/resizable"
import type { ResizableStorage } from "@ui-sdk/web"
const session: ResizableStorage = {
getItem: (key) => sessionStorage.getItem(key),
setItem: (key, value) => sessionStorage.setItem(key, value),
}
function mount(root: HTMLElement) {
const group = document.createElement("ui-resizable")
group.storage = session
group.setAttribute("auto-save-id", "docs-storage")
group.innerHTML = `
Messages
Inès Moreau
Kofi Mensah
Wren Takahashi
Inès Moreau
Can we move the review to Friday?
`
root.replaceChildren(group)
}
export { mount }
```
Resize Messages, then reload. The width comes back in this tab, but not in a new one.
A server can't read `localStorage`, so it renders each panel's `default-size` and the saved layout arrives when the elements attach. To render the saved layout on the first paint, keep it in a cookie and write the sizes into each panel's `default-size`. Here your server reads them from the request's `Cookie` header. It imports `resizableStorageKey`, which names the cookie:
```ts title="server.ts"
import { resizableStorageKey } from "@ui-sdk/core/resizable"
function editor(cookie: string | null) {
const value = cookie?.match(
new RegExp(`(?:^|; )${resizableStorageKey("editor")}=([^;]*)`)
)?.[1]
const saved = value ? JSON.parse(decodeURIComponent(value)) : {}
const [sidebar = 25, main = 75] = saved["sidebar,main"] ?? []
return ``
}
```
```ts title="page.ts"
import "@ui-sdk/web/resizable"
import type { ResizableStorage } from "@ui-sdk/web"
const cookieStorage: ResizableStorage = {
getItem: (key) => {
const value = document.cookie.match(
new RegExp(`(?:^|; )${key}=([^;]*)`)
)?.[1]
return value === undefined ? null : decodeURIComponent(value)
},
setItem: (key, value) => {
document.cookie = `${key}=${encodeURIComponent(value)}; path=/; max-age=31536000`
},
}
document.querySelector("ui-resizable")!.storage = cookieStorage
```
## Controller
The element's `api` collapses, expands and resizes panels from anywhere, by id or index, and reads the layout with `getLayout()`. Changes it makes report the `imperative` reason.
```ts title="controller.ts"
import "@ui-sdk/web/resizable"
import { log } from "./log"
function mount(root: HTMLElement) {
root.innerHTML = `
Files
page.tsx
layout.tsx
globals.css
page.tsx
Saved just now
`
const editor = root.querySelector("ui-resizable")!.api
const actions: Record void> = {
collapse: () => editor.collapse("controller-sidebar"),
expand: () => editor.expand("controller-sidebar"),
resize: () => editor.resize("controller-sidebar", "240px"),
read: () =>
log(
root,
`Layout ${editor.getLayout().map(Math.round).join(" / ")}${editor.isCollapsed("controller-sidebar") ? ", collapsed" : ""}`
),
}
root
.querySelectorAll("[data-action]")
.forEach((button) => {
button.addEventListener("click", () => actions[button.dataset.action!]())
})
}
export { mount }
```
Use Collapse, Expand and 240px to move Files from outside the group, and Read to log its sizes.
## Step Size
`step` sets how far an arrow key moves a handle, 1% by default, and `large-step` how far Shift with an arrow moves it, 10% by default.
```ts title="keyboard.ts"
import "@ui-sdk/web/resizable"
function mount(root: HTMLElement) {
root.innerHTML = `
Original
v1.2.0
Changes
v1.3.0
`
}
export { mount }
```
Focus the handle between Original and Changes. The arrow keys move it 5%, Shift with an arrow 25%, and Home and End as far as it goes.
## Disabled
`disabled` on a handle fixes it in place. On the group it fixes every handle. Disabled handles leave the tab order, and their panels keep their sizes. A disabled `