Documentation
Guides

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.

Checks are an opt-in feature: checkboxes(), from @fragiola/tree/checkboxes (re-exported by every adapter's /checkboxes entry). A tree that never imports it does not ship it. Installed, it holds the checks in the model (state.checkedItemIds), puts aria-checked on every item (mixed included), makes Space toggle the focused item's check (when the tree has no selection(), or with checkboxes({ space: "check" })), and gives each item its check state (checked, indeterminate, checkState, and data-checked / data-indeterminate). The box is yours: any control that reads that state and runs item.toggle-check. The package renders none. What a check means (a scope to grant, a filter to apply) is yours too.

Turning them on

import { type ItemOf, Tree, useTree, useTreeItem } from "@fragiola/tree-react";
import { checkboxes } from "@fragiola/tree-react/checkboxes";

const features = [checkboxes()] as const;

function CheckBox({ item }: { item: ItemOf<Types> }) {
    const { model } = useTree<Types, typeof features>();
    const { state } = useTreeItem(item);
    return (
        <span
            aria-hidden
            data-tree-no-drag=""
            className="box"
            data-checked={state.checked ? "" : undefined}
            data-indeterminate={state.indeterminate ? "" : undefined}
            onClick={() => model.run("item.toggle-check", { itemId: item.id })}
        >
            <CheckIcon className="check" aria-hidden />
            <MinusIcon className="dash" aria-hidden />
        </span>
    );
}

function PermissionItem({ item }: { item: ItemOf<Types> }) {
    return (
        <Tree.Item item={item}>
            <Tree.ItemContent className="row">
                <Tree.Toggle>▸</Tree.Toggle>
                <CheckBox item={item} />
                <span>{item.label}</span>
            </Tree.ItemContent>
            <Tree.Group<Types>>{(child) => <PermissionItem item={child} />}</Tree.Group>
        </Tree.Item>
    );
}

export function Permissions() {
    return (
        <Tree.Root<Types, typeof features>
            defaultTree={json}
            features={features}
            aria-label="Permissions"
        >
            <Tree.Items<Types>>{(item) => <PermissionItem item={item} />}</Tree.Items>
        </Tree.Root>
    );
}
.box .check,
.box .dash {
    display: none;
}
.box[data-checked] .check,
.box[data-indeterminate] .dash {
    display: block;
}

In Vue, tree.ts holds features = [checkboxes()] as const (from @fragiola/tree-vue/checkboxes) and Tree = typedTree<Types, typeof features>(). A press on the box toggles the check (item.toggle-check); a press on the rest of the row still selects (with selection()). The item carries aria-checked (true, false or "mixed"), and Space acts on it, so the box is an element that never takes focus, hidden from assistive technology (aria-hidden): a screen reader reads the item, not a second checkbox inside it, and a press focuses the item, so the arrows keep working. data-tree-no-drag keeps a press on it from starting a drag or a selection. A button would take focus when clicked and keep the tree's keys to itself.

Tri-state checkboxes
Gallery

Cascade or independent

settings.checkMode is "cascade" (the default) or "independent":

  • cascade: checking a parent checks its descendants; a parent is checked when all its children are, and mixed when only some of its descendants are. Children loaded later inherit a checked parent. A mixed parent is never stored: model.get("check-state-by", { itemId }) computes it, and checkedItemIds holds the fully checked items only.
  • independent: each item is checked on its own (a filter where a category and its entries mean different things).
model.run("tree.configure", { settings: { checkMode: "independent" } });

From code

model.run("item.check", { itemId: "billing", checked: true });
model.run("item.toggle-check", { itemId: "billing.read" });
model.get("check-state-by", { itemId: "billing" }); // "checked" | "unchecked" | "mixed"
model.is("item-checked", { itemId: "billing" });

A disabled item cannot be checked or unchecked.

Reading what is checked

In cascade mode, checkedItemIds lists parents and their children alike. Keep what your app saves, here the leaves' data:

const scopes = useTreeState<Types, string>(
    (state) =>
        state.checkedItemIds
            .flatMap((itemId) => {
                const item = state.items[itemId];
                return item?.kind === "permission" ? [item.data.scope] : [];
            })
            .join(" "),
    { model },
);

The selector returns a string so that Object.is sees an unchanged selection as equal; pass isEqual to compare arrays instead. To keep the checks in your app's state, control checkedItemIds on the root (with onCheckedItemIdsChange in React, v-model:checked-item-ids in Vue, [(checkedItemIds)] in Angular: Controlled state).