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

Hooks

useSplitter reaches the model and engine, useSplitterState follows one of its answers; useGroup, usePanel and useSeparator are the layer under each part.

The hooks are the lower layer of the primitives. useSplitter is the one an app calls most: it gives a component inside a group (or anywhere, with a ref) the model and the engine; useSplitterState re-renders it when an answer of the model changes. useGroup, usePanel and useSeparator return a part's state and the props of its element, to build a part of your own; useSplitterRef is on External ref.

useSplitter

import { useSplitter } from "@fragiola/splitter-react";

function ResetButton() {
    const { model, groupId } = useSplitter(); // inside a Splitter.Group
    return (
        <button type="button" onClick={() => model.run("group.reset", { groupId })}>
            Reset
        </button>
    );
}
  • useSplitter<T>(): inside a Splitter.Group, its model and engine, and the enclosing group's id. It throws outside a group.
  • useSplitter<T>(splitterRef): the root group's that holds the ref, from anywhere, or null while none does. It re-renders when a group takes or releases the ref.

It returns a SplitterContextValue<T>:

fieldtypedescription
modelSplitterModel<T>the model of every group of the splitter (see Model)
engineSplitterEnginethe engine of its groups on screen (see Engine)
groupIdGroupIdOf<T>the enclosing group (inside a group), or the root group (through a ref)

The hook returns stable objects: it does not re-render on every model change. Follow a value with useSplitterState, the parts' callbacks, or model.subscribe.

useSplitterState

import { useSplitterState } from "@fragiola/splitter-react";

function SidebarStatus() {
    const collapsed = useSplitterState(({ model }) =>
        model.is("panel-collapsed", { panelId: "sidebar" }),
    );
    return <p>{collapsed ? "Sidebar hidden" : "Sidebar shown"}</p>;
}

useSplitterState<T, S>(selector, options?) answers selector(splitter, state) and re-renders the component only when that answer changes. splitter is what useSplitter returns (model, engine, groupId) and state the model's state. The selector runs once per model state (and again when it is a new function): keep it pure, and ask the model with get and is.

optiontypedescription
splitterRefSplitterRefthe splitter to read: the root group's that holds the ref, from anywhere. The hook answers undefined while none does. Default: the enclosing Splitter.Group's (it throws outside one)
isEqual(a: S, b: S) => booleanwhether two answers are the same, so the component does not re-render (default Object.is)

An answer compared with Object.is should be a value or an object of the state (a model.get("layout-by", …) is the state's own object, kept while it does not change). A selector that builds an object or an array each time (model.get("panel-size-by", …), a .map) needs an isEqual, or picks a value out of it (?.percentage). It follows the model only: the engine's answers (dragging-separator-id) are read in the engine's own events.

useGroup

useGroup() returns the enclosing group's state and the props of its element (UseGroupResult). Splitter.Group creates or joins the model and registers the group; this hook only reads it, so it serves a component inside a group that wants the group's state:

import { useGroup } from "@fragiola/splitter-react";

function DragHint() {
    const { state } = useGroup();
    return state.dragging ? <p role="status">Release to apply the new size</p> : null;
}
fieldtypedescription
stateGroupPartStateid, orientation, disabled, dragging, path (see Group)
props{ ref, style } & data-*the ref that binds the group's element, its structural style and its data-*

usePanel

usePanel(options) registers a panel in the enclosing group and returns its state and the props of its element (UsePanelResult). The options (UsePanelOptions<T>) are the props of Splitter.Panel: id, minSize, maxSize, defaultSize, collapsible, collapsedSize, collapsedThreshold, disabled, groupResizeBehavior, onResize, onCollapse and onExpand.

fieldtypedescription
statePanelPartStateid, size, collapsed, collapsible, disabled, path (see Panel)
props{ id, ref, style } & data-*its DOM id (the panel id), the ref that binds it, its structural style, its data-*

A group nested inside an element of your own built on usePanel does not nest in it: use Splitter.Panel as the parent of a nested group.

useSeparator

useSeparator(options) binds a separator element of the enclosing group (its options run separator.update) and returns its state and the props of its element (UseSeparatorResult). The options (UseSeparatorOptions) are disabled and resetOnDoubleClick.

import { useSeparator } from "@fragiola/splitter-react";

export function Rule({ label }: { label: string }) {
    const { props } = useSeparator();
    return <hr {...props} aria-label={label} />;
}
fieldtypedescription
stateSeparatorPartStateid, orientation, disabled, dragging, path (see Separator)
props{ ref, role, tabIndex, style } & ARIA & data-*the ref that binds it (the engine listens to its pointer, keyboard and double click events), role="separator", its Window Splitter ARIA values, tabIndex (none while disabled), its structural style and data-*

Every field

The hooks' types, field by field:

fieldofdescription
stateUseGroupResult, UsePanelResult, UseSeparatorResultthe part's state
propsUseGroupResult, UsePanelResult, UseSeparatorResultwhat goes on the part's element
idGroupPartState, PanelPartState, SeparatorPartState, UsePanelOptionsthe part's id
orientationGroupPartState, SeparatorPartStatethe group's orientation, or the separator's own
disabledevery state, UsePanelOptions, UseSeparatorOptionsthe part cannot be used, or is not moved by a separator
draggingGroupPartState, SeparatorPartStatea pointer drags the separator, or one of the group's
pathevery stateits path, once registered
sizePanelPartStatethe panel's size in percent
collapsedPanelPartStatethe panel is collapsed
collapsiblePanelPartState, UsePanelOptionsthe panel can collapse
minSize, maxSize, defaultSize, collapsedSize, collapsedThreshold, groupResizeBehaviorUsePanelOptionsthe panel's constraints
onResize, onCollapse, onExpandUsePanelOptionsthe panel's callbacks
resetOnDoubleClickUseSeparatorOptionsa double click resets its panel
model, engine, groupIdSplitterContextValuewhat useSplitter returns
splitterRef, isEqualUseSplitterStateOptionsthe splitter useSplitterState reads, and when two answers are the same