Documentation
Guides

Collapsible panels

Let a panel snap shut past a threshold and come back at the size it had, from a drag, the Enter key, a button or code, with its state on data-collapsed.

A collapsible panel can go below its minimum, to its collapsed size, and remembers the size it had so expanding gives it back. The package decides when it snaps, records the restore size and reports the change; the button, the icon and what the panel shows while collapsed are yours.

Making a panel collapsible

<Splitter.Panel
    id="sidebar"
    defaultSize="25%"
    minSize="10rem"
    collapsible
    collapsedSize="3rem"
    onCollapse={() => console.log("collapsed")}
    onExpand={() => console.log("expanded")}
>
    …
</Splitter.Panel>
  • collapsible lets it collapse; without it the panel never goes below minSize.
  • collapsedSize is its size collapsed, in any unit (default 0): a rail of icons, a strip with a title, or nothing.
  • collapsedThreshold is how far past its minimum a drag goes before it snaps shut (default: halfway between the collapsed size and the minimum).
  • onCollapse and onExpand fire when its state changes, whatever changed it.

While collapsed the panel carries data-collapsed, and model.is("panel-collapsed", { panelId }) answers true: a component follows it with useSplitterState.

Collapsible sidebar
Gallery

Every way to collapse it

howwhat runs
dragging the separator past the thresholdseparator.move: the panel snaps to its collapsed size
dragging it back past the thresholdseparator.move: the panel snaps to its minimum, then follows the pointer
Enter on the separator after itseparator.move (source: "keyboard") to its collapsed size, or back to its restore size when it is collapsed
Home on that separatormoves to the smallest size: collapsed, for a collapsible panel
codemodel.run("panel.collapse", { panelId }) / model.run("panel.expand", { panelId })

Enter acts on the panel before the separator, and moves that separator only, as the arrows do: a disabled panel keeps its size, and when the panels on the other side cannot take the space, the panel does not collapse (panel.collapse from code may still). For a panel at the end of a group (a terminal under an editor), drag it or use code.

A toggle button

Outside the group, reach the model through an external ref and follow the state with useSplitterState, which re-renders the button whenever the panel collapses or expands, however that happens:

"use client";

import { Splitter, useSplitter, useSplitterRef, useSplitterState } from "@fragiola/splitter-react";

export function Workbench() {
    const splitterRef = useSplitterRef();
    const splitter = useSplitter(splitterRef);
    const collapsed =
        useSplitterState(({ model }) => model.is("panel-collapsed", { panelId: "sidebar" }), {
            splitterRef,
        }) ?? false; // undefined until the group holds the ref
    function toggle() {
        splitter?.model.run(collapsed ? "panel.expand" : "panel.collapse", { panelId: "sidebar" });
    }
    return (
        <>
            <button type="button" aria-pressed={!collapsed} onClick={toggle}>
                Sidebar
            </button>
            <Splitter.Group splitterRef={splitterRef} className="h-96">
                <Splitter.Panel
                    id="sidebar"
                    defaultSize="25%"
                    minSize="15%"
                    collapsible
                >
                    …
                </Splitter.Panel>
                <Splitter.Separator aria-label="Resize sidebar" className="w-1" />
                <Splitter.Panel id="main">…</Splitter.Panel>
            </Splitter.Group>
        </>
    );
}

The size it comes back to

Whenever a change collapses a panel, the model records its size before as its restore size (restoreSize in the state and in the saved document). A drag records it on release, from where the drag started: its transient steps record nothing, so a vetoed drag leaves it as it was. panel.expand gives it back, as far as the other panels can make room; with no restore size, the panel expands to its minimum (1% when its minimum is 0). A collapsed panel saved in the JSON document comes back collapsed, and still expands to the size it had.

When it is refused

panel.collapse and panel.expand are refused on a panel that is not collapsible, and when the other panels cannot make room within their own constraints. Ask first with model.can, and follow the answer with useSplitterState:

function ShowTerminal() {
    const { model } = useSplitter();
    const canExpand = useSplitterState(({ model }) =>
        model.can("panel.expand", { panelId: "terminal" }),
    );
    return (
        <button
            type="button"
            disabled={!canExpand}
            onClick={() => model.run("panel.expand", { panelId: "terminal" })}
        >
            Show the terminal
        </button>
    );
}

Hiding what is collapsed

A panel collapsed to 0 is still in the document. Hide its content from assistive technology as well as from sight: in-data-collapsed:hidden on the content (Tailwind), a [data-collapsed] > * rule (CSS), or render the content from your collapsed state.