Controlled state
Own the expanded, selected and checked items in your app state, decide what each change becomes, and keep the tree in step with your app.
By default the model owns its state, and you read it with useTreeState. When your app wants to
own a list (to sync it with the URL, a store or another view), the root takes it as a controlled
prop, with a callback for every change the tree would make:
| prop | callback |
|---|---|
expandedItemIds | onExpandedItemIdsChange |
selectedItemIds | onSelectedItemIdsChange |
checkedItemIds | onCheckedItemIdsChange |
Each pair is independent: control the selection and leave the expansion to the model. The selection is the selection feature's list (Features): it
needs selection() in the model's features, and compiles only then.
Controlling the expansion
import { Tree } from "@fragiola/tree-react";
import { useState } from "react";
export function Outline() {
const [expandedItemIds, setExpandedItemIds] = useState<string[]>(["src"]);
return (
<>
<button type="button" onClick={() => setExpandedItemIds([])}>
Collapse all
</button>
<Tree.Root<Types>
defaultTree={json}
expandedItemIds={expandedItemIds}
onExpandedItemIdsChange={setExpandedItemIds}
aria-label="Outline"
>
<Tree.Items<Types>>{(item) => <OutlineItem item={item} />}</Tree.Items>
</Tree.Root>
</>
);
}Deciding what a change becomes
The callback receives the list the tree would have; the prop decides what it has. A change the app does not accept is reverted: here a pinned folder stays open.
const change = (itemIds: string[]) =>
setExpandedItemIds(itemIds.includes("src") ? itemIds : ["src", ...itemIds]);
<Tree.Root<Types>
defaultTree={json}
expandedItemIds={expandedItemIds}
onExpandedItemIdsChange={change}
aria-label="Outline"
>
<Tree.Items<Types>>{(item) => <OutlineItem item={item} />}</Tree.Items>
</Tree.Root>;How it works
Controlled props are commands too. When a prop differs from the model, the root runs the commands
that bring the model to it (item.expand, item.collapse, tree.select, item.check), as one
batch, before the tree shows it (before paint in React, before mount and after each change of the
prop in Vue, whenever the input changes in Angular), with meta.source set to "controlled";
those commits report no change. Every other commit that changes a list reports the new list
(onExpandedItemIdsChange and the other callbacks in React, the update:* events in Vue, the
…Change outputs in Angular). So:
- your middleware sees the controlled changes too, and can tell them apart by their
meta; - an id the tree does not have is skipped rather than failing the rest (an expansion or a check the model refuses, a disabled item's, is skipped too);
- in cascade mode,
checkedItemIdsis normalized by the model (checking a parent checks its children), so the list you get back may hold more ids than you set.
When not to control
Controlled props are for state the app shares. To read the state, useTreeState (injectTreeState
in Angular) is enough; to
change it from a button, run a command (model.run("tree.collapse-all", {})); to save it, the
document holds all of it (Saving and restoring).
Checkboxes
Tri-state checks for permission pickers and filters - checks that cascade to children and back up as mixed parents, with a check control of your own.
Saving and restoring
The whole tree is one JSON document. Save it after each change, restore it at load, and replace it later without losing the model.