Documentation
API: primitives (@fragiola/splitter-react)

Group

Splitter.Group lays out its panels side by side or stacked, creates the model for the whole splitter, and takes a controlled or a default layout.

Splitter.Group is a flex container whose Splitter.Panels share its room, with a Splitter.Separator between each pair. The outermost group creates the model and the engine (unless you pass a model); a group inside a Splitter.Panel joins them and nests in that panel. It renders a div with no role and no name: your markup decides what it is.

import { type Layout, Splitter } from "@fragiola/splitter-react";
import { useState } from "react";

export function Controlled() {
    const [layout, setLayout] = useState<Layout>({ left: 30, right: 70 });
    return (
        <Splitter.Group id="main" layout={layout} onLayoutChange={(next) => setLayout({ ...next })} className="h-80">
            <Splitter.Panel id="left">…</Splitter.Panel>
            <Splitter.Separator aria-label="Resize left" className="w-1" />
            <Splitter.Panel id="right">…</Splitter.Panel>
        </Splitter.Group>
    );
}

Group is also a named export (import { Group } from "@fragiola/splitter-react"), the same component.

Props

GroupProps<T> extends the common primitive props and every div attribute.

proptypedefaultdescription
idGroupIdOf<T>generated (useId)the group's id, as the saved layout names it
orientation"horizontal" | "vertical""horizontal"panels side by side, or stacked
disabledbooleanfalsenone of its separators can be used (code can still resize its panels)
modelSplitterModel<T>a new one (root), the parent's (nested)the model to register in; a nested group given one is a root of its own
layoutLayoutnonethe layout (each panel's size in percent, by panel id), applied when the group registers and whenever its values change to other than the model's layout (group.set-layout); pair it with onLayoutChange
defaultLayoutLayoutnonethe layout it starts with, unless the model has a saved one for it
onLayoutChange(layout: Readonly<Layout>) => voidnonethe layout changed: on every commit, drag steps and the registration included
onLayoutCommit(layout: Readonly<Layout>) => voidnonethis group's layout was committed: a drag released, a key pressed, a command run (never a drag step, another group's commit, nor what the markup runs: registering, a controlled layout)
splitterRefSplitterRefnonegives code outside the group its model and engine (a root group only); see External ref
keyboardStepnumber5how far an arrow key moves a separator, in percent (a root group only, read once)
resetOnDoubleClickbooleantruea double click on a separator resets its panel (a root group only, read once)
childrenReactNodenoneits panels and separators, at any depth of your components

A layout the model refuses (it does not name the group's panels) is ignored; a valid one is clamped to the constraints. A layout that comes back from onLayoutChange equals the model's layout and runs nothing, so drag steps stay transient and a veto still puts the drag's origin back. The adapter does not snap the model back when you ignore onLayoutChange: a middleware vetoes the changes your app refuses.

State

GroupPartState, what className, style and render receive (also returned by useGroup):

fieldtypedescription
idstringthe group's id
orientation"horizontal" | "vertical"its orientation
disabledbooleannone of its separators can be used
draggingbooleana pointer is dragging one of its separators
pathstring | undefinedits path (/g0, /g0/p1/g0); undefined until it registers

Data attributes

attributevalue
data-splitter-part"group"
data-splitter-pathits path (see Paths)
data-orientation"horizontal" or "vertical"
data-disabledpresent when disabled
data-draggingpresent while one of its separators is dragged

Structural style

display: flex, flex-direction: row (horizontal) or column (vertical), flex-wrap: nowrap. Its size is yours: see Sizing the group.

Commands

Registering runs one batch: group.add, a panel.add per panel, and group.set-layout for layout (else defaultLayout when the model saved no layout for the group). Changing orientation or disabled runs group.update, and so does a nested group whose panel gets another id (its new parentPanelId: the group stays where it is, with its layout); unmounting runs group.remove (keeping a layout the user changed, so a remount restores it).

Common props

Every part (Splitter.Group, Splitter.Panel, Splitter.Separator) takes these, on top of the attributes of the element it renders (PrimitiveProps<State>):

proptypedescription
renderRenderProp<State>replaces the element: an element (its props merged with the part's) or (props: RenderedProps, state) => element (never asChild)
classNamestring | ((state) => string | undefined)a class, or a function of the part's state
styleCSSProperties | ((state) => CSSProperties | undefined)a style, or a function of the state; the structural keys always win
refRef<HTMLElement>merged with the part's own ref

RenderedProps are the props a render function spreads: the element's attributes, a callback ref that fits any element, and the data-*. See The primitive contract.