Splitter
StableA draggable bar between two panes that people can also move with the keyboard.
Also known as resizable, resizable panels, split view, split pane
Install with npm install @tattva/ui (setup), or copy the code from the kit in Downloads.
Sidebar and main area
Sidebar (160px)
Main area. Drag the bar, or focus it and press the arrow keys.
function Example() {
const [w, setW] = useState(160);
return (
<div className="flex h-40 w-full max-w-lg overflow-hidden rounded-card border border-line bg-surface text-body leading-5 text-fg">
<div style={{ width: w }} className="shrink-0 overflow-hidden bg-sunken p-3">Sidebar ({w}px)</div>
<Splitter direction="horizontal" label="Resize sidebar" value={w} onChange={setW} min={96} max={300} />
<div className="min-w-0 flex-1 p-3">Main area. Drag the bar, or focus it and press the arrow keys.</div>
</div>
);
}Horizontal means a vertical bar between left and right panes. The first pane gets its width from the value.
When to use it
Lets people change how much room a side pane or panel gets. It works with a mouse, a finger and the keyboard.
Made of: Bar · Line · Hit area
Use it for
- A resizable sidebar next to the main area.
- A split between an editor and its output.
- A pane people can collapse with a double click.
Not for
- Showing or hiding content without resizing: use Collapsible.
- Switching between views: use Tabs.
Do and avoid
Invoices
Receipts
Receipts
Invoice 0142
Invoices
Invoice 0142
Do
- Put the bar in a flex row or column between the two panes.
- Set min and max so neither pane can disappear by accident.
- Save the size so it comes back next visit.
- Offer a button as well when a pane can collapse.
Avoid
- Do not expect it to size the panes. You set the first pane from value.
- Do not leave out the label.
- Do not use it to switch views. Use Tabs.
- Do not make the first pane smaller than its content needs without a way to bring it back.
On a phone
- It is dragged with a finger, and the handle gets a wider invisible touch area on touch screens.
- The drag handles pointer events only and stops the page from scrolling while the finger is on the handle.
- Arrow keys and double click do not exist on a phone, so offer a button that does the same job as onToggle.
- The value, min and max are pixels that you pass in, so choose limits that leave room on a 360px screen.
Properties
| Prop | Type | Default | Description |
|---|---|---|---|
| directionrequired | "horizontal" | "vertical" | none | horizontal is a vertical bar between left and right panes. vertical is a horizontal bar between top and bottom panes. |
| valuerequired | number | none | Size of the first pane in px. |
| onChangerequired | (px: number) => void | none | Called with the new size, already clamped between min and max. |
| minrequired | number | none | Smallest size of the first pane in px. |
| maxrequired | number | none | Largest size of the first pane in px. |
| labelrequired | string | none | Accessible name of the bar. |
| onToggle | () => void | none | Called on double click and on Enter. Use it to collapse or restore the first pane. Without it neither does anything. |
| step | number | 16 | Keyboard step in px. Shift multiplies it by 4. |
| className | string | none | Classes for the bar. In a flex row it fills the height; in a flex column it fills the width. |
"Show code under the preview gives the code for the example on the stage."
States
States this part has beyond its default look. Build each one your screen can reach. States set by a property are in the Code tab.
- hover
- The line darkens when the pointer is over the bar.
- dragging
- While the bar is pressed and moved, the line is thicker and uses the accent colour.
- focus
- A visible focus ring appears on the bar when you reach it with the keyboard.
- at limit
- At min or max the size stops changing, and aria-valuenow stays at that limit.
Tokens
Change one of these and every part that uses it follows.
--border--border-strong--accent--dur-fast--focus-ring
Built in
- The bar has role separator with aria-orientation, aria-valuenow, aria-valuemin and aria-valuemax, and can be focused with Tab.
- Arrow keys along the bar's axis resize by step. Shift makes the step four times larger. Home goes to min and End goes to max.
- Enter calls onToggle when you pass it.
- Dragging uses pointer capture, so the drag keeps working if the pointer leaves the bar. It works with mouse, pen and touch.
- The size is always held between min and max.
- The bar is 12px wide, and 44px wide on touch screens through an invisible larger target.
- The line darkens on hover, focus and drag, and the focus ring is the global one. The cursor shows col-resize or row-resize.
What you need to do
- Give the bar a label that names what it resizes, such as "Resize sidebar".
- Draw the panes yourself and size the first from the same value. Splitter does not lay anything out.
- Clamp saved sizes when you restore them, and offer a way to reset.
- If a pane can collapse, tell people how, because the double click and Enter are not visible.
Built toward WCAG 2.2 AA and checked automatically; no independent audit yet. Read the accessibility guide