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 aSplitter.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, ornullwhile none does. It re-renders when a group takes or releases the ref.
It returns a SplitterContextValue<T>:
| field | type | description |
|---|---|---|
model | SplitterModel<T> | the model of every group of the splitter (see Model) |
engine | SplitterEngine | the engine of its groups on screen (see Engine) |
groupId | GroupIdOf<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.
| option | type | description |
|---|---|---|
splitterRef | SplitterRef | the 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) => boolean | whether 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;
}| field | type | description |
|---|---|---|
state | GroupPartState | id, 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.
| field | type | description |
|---|---|---|
state | PanelPartState | id, 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} />;
}| field | type | description |
|---|---|---|
state | SeparatorPartState | id, 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:
| field | of | description |
|---|---|---|
state | UseGroupResult, UsePanelResult, UseSeparatorResult | the part's state |
props | UseGroupResult, UsePanelResult, UseSeparatorResult | what goes on the part's element |
id | GroupPartState, PanelPartState, SeparatorPartState, UsePanelOptions | the part's id |
orientation | GroupPartState, SeparatorPartState | the group's orientation, or the separator's own |
disabled | every state, UsePanelOptions, UseSeparatorOptions | the part cannot be used, or is not moved by a separator |
dragging | GroupPartState, SeparatorPartState | a pointer drags the separator, or one of the group's |
path | every state | its path, once registered |
size | PanelPartState | the panel's size in percent |
collapsed | PanelPartState | the panel is collapsed |
collapsible | PanelPartState, UsePanelOptions | the panel can collapse |
minSize, maxSize, defaultSize, collapsedSize, collapsedThreshold, groupResizeBehavior | UsePanelOptions | the panel's constraints |
onResize, onCollapse, onExpand | UsePanelOptions | the panel's callbacks |
resetOnDoubleClick | UseSeparatorOptions | a double click resets its panel |
model, engine, groupId | SplitterContextValue | what useSplitter returns |
splitterRef, isEqual | UseSplitterStateOptions | the splitter useSplitterState reads, and when two answers are the same |
Splitter.Separator
Splitter.Separator sits between two panels and resizes them with the pointer, the Window Splitter keys or a double click, with its ARIA values set for you.
External ref
useSplitterRef and createSplitterRef give code outside the root group (a toolbar, a menu, a store) the splitter's model and engine, and follow it as it mounts.