Components / Structure

SplitPane

Two panes with a divider people can move, by dragging it or with the keyboard.

Source Edit this page

Awindow splitter

When to use

List and detail, editor and preview, code and output: two regions whose balance depends on the task.

Use something else when:

the side region is navigation: AppShell
the second region is temporary: a Sheet

Usage

tsx

import { SplitPane } from "@arshad-shah/cynosure";

<div style={{ blockSize: "100%" }}>
  <SplitPane label="Resize the file list" start={<FileList />} end={<Preview />} defaultSize={30} />
</div>

The SplitPane fills its container, so give the container a size. Each pane scrolls on its own. Remember the size by passing size and onSizeChange, and save it in onResizeEnd.

Stacked and collapsible

orientation="vertical" stacks the panes. With collapsible, Enter on the divider collapses the start pane and restores it.

Sidebars and docks

anchor="end" gives the size to the end pane, so with unit="px" a right sidebar or a bottom dock keeps its pixels as the window grows and the start pane takes the rest. collapsed, defaultCollapsed and onCollapsedChange collapse the anchored pane from a menu or a button; its size is kept and comes back when it expands. onResizeEnd is called once, with the final size, when a drag is released or a resize key is let go: the moment to save the size.

tsx

<SplitPane
  label="Resize the results"
  orientation="vertical"
  unit="px"
  anchor="end"
  start={<Editor />}
  end={<Results />}
  defaultSize={240}
  onResizeEnd={saveHeight}
  collapsed={!resultsOpen}
  onCollapsedChange={(collapsed) => setResultsOpen(!collapsed)}
/>

Props

Every prop of SplitPane
Prop	What it does	Type	Default
`start`Required	The first pane (left, or right in right-to-left text; top when vertical).	`ReactNode`
`end`Required	The second pane (right, or left in right-to-left text; bottom when vertical).	`ReactNode`
`label`Required	Accessible name of the divider, e.g. "Resize the file list".	`string`
`orientation`	`horizontal`: panes side by side. `vertical`: stacked.	`"horizontal" \| "vertical"`
`unit`	`percent` (default): sizes are percent of the whole. `px`: the sized pane (see `anchor`) has a fixed width (or height) in pixels, such as a sidebar that keeps its size as the window grows.	`"percent" \| "px"`
`anchor`	Which pane the size, limits, collapse and divider value belong to. `start` (default): the first pane, such as a left sidebar. `end`: the second pane, such as a right sidebar or a bottom dock that keeps its pixels as the window grows.	`"start" \| "end"`
`size`	Size of the sized pane (see `anchor`), in `unit`. Kept while it is collapsed, so expanding restores it.	`number`
`defaultSize`	Starting size of the sized pane when uncontrolled, in `unit`. Default 50 percent, or 240 pixels.	`number`	`50 percent`
`onSizeChange`	Called with the new size as the divider moves, on every step of a drag or key.	`((size: number) => void)`
`onResizeEnd`	Called once with the final size when a resize ends: the pointer is released, or the arrow (or Page, Home, End) key is let go. Not called when nothing changed or the drag was cancelled. Use it to save the size.	`((size: number) => void)`
`min`	Smallest size of the sized pane, in `unit`. Default 10 percent, or 120 pixels.	`number`	`10 percent`
`max`	Largest size of the sized pane, in `unit`. Default 90 percent, or 600 pixels.	`number`	`90 percent`
`step`	Arrow keys move by this much, in `unit`. Default 5 percent, or 16 pixels.	`number`	`5 percent`
`collapsible`	Enter on the divider collapses the sized pane to 0 and restores it. Default true when `collapsed` or `defaultCollapsed` is given, false otherwise.	`boolean`	`true`
`collapsed`	Whether the sized pane is collapsed, for a sidebar or dock toggled from a menu or button. Its size is kept.	`boolean`
`defaultCollapsed`	Whether the sized pane starts collapsed when `collapsed` is not controlled.	`boolean`
`onCollapsedChange`	Called when the divider collapses or expands the pane (Enter, or a key or drag that opens it).	`((collapsed: boolean) => void)`
`className`	Added to the root element, for layout.	`string`
`style`	Layout only. Restyle through --cy-split-pane-* tokens.	`CSSProperties`

Generated from the type definitions in @arshad-shah/cynosure 0.5.0.

Behaviour and accessibility

Role: the divider is a focusable separator named by label, with the anchored pane's size (the start pane unless anchor="end"; 0 when collapsed) as aria-valuenow and aria-controls pointing at that pane.
Keyboard: the keys move the divider, so the anchored pane grows or shrinks with it.

Behaviour and accessibility, table 1
Key	Action
Arrow Left / Right	Move the divider (side by side; flipped in right-to-left text)
Arrow Up / Down	Move the divider (stacked)
Home / End	The anchored pane to `min` / `max`
Enter	Collapse or restore the anchored pane (with `collapsible`, `collapsed` or `defaultCollapsed`)

Collapsed, a key that grows the pane opens it at min; the others leave it closed. onResizeEnd fires when the key is let go.

Pointer and touch: drag the divider; it keeps focus afterwards so the keys can fine-tune. Dragging a collapsed divider opens the pane, and Escape puts back the size and collapse the drag began with. Its hit area is at least 24px wide, 44px on touch screens, and touch dragging does not scroll the page.
Direction: the start pane is on the right in right-to-left text.

Theming

Tokens: --cy-split-pane-divider-size and --cy-split-pane-divider.

AppShell · Slider

These examples run Cynosure 0.5.0 (commit 50ce30b), the version on npm.

When to useLink to "When to use"

UsageLink to "Usage"

Stacked and collapsibleLink to "Stacked and collapsible"

Sidebars and docksLink to "Sidebars and docks"

PropsLink to "Props"

Behaviour and accessibilityLink to "Behaviour and accessibility"

ThemingLink to "Theming"

RelatedLink to "Related"