Checkbox Tree

A dependency-free, instance-based checkbox tree for browser ES modules. It supports cascading selection, indeterminate parent states, expandable branches, multiple independent instances, optional local-storage persistence, and compact shareable URL state backed by an append-only node manifest.

Install

npm install @aaronaxvig/checkbox-tree

The package is not published yet. During local development, install it by path:

npm install ../checkbox-tree

Usage

import { CheckboxTree } from "@aaronaxvig/checkbox-tree";
import "@aaronaxvig/checkbox-tree/styles.css";

const tree = new CheckboxTree(document.querySelector("#example-tree"), {
  initiallySelected: true,
  storageKey: "example-tree-state",
  onSelectionChange({ selectedIds, selectedNodes }) {
    console.log(selectedIds, selectedNodes);
  },
});

tree.setData([
  {
    id: "fruit",
    label: "Fruit",
    children: [
      { id: "apple", label: "Apple", metadata: { color: "red" } },
      { id: "pear", label: "Pear", metadata: { color: "green" } },
    ],
  },
]);

For applications without a bundler, serve or copy the src/ directory and use relative URLs. The main module imports its state-codec modules alongside it:

<link rel="stylesheet" href="./checkbox-tree.css">
<script type="module">
  import { CheckboxTree } from "./checkbox-tree.js";
</script>

Every node requires unique string id and label properties. Nodes may also have children, application-owned metadata, and selectable or disabled flags.

API

new CheckboxTree(container, options) creates an independent instance.
setData(nodes) validates and renders nodes, then restores saved state.
getSelectedIds() returns selected node IDs.
getSelectedNodes() returns selected source node objects.
setSelectedIds(ids, { notify }) replaces the selection.
restoreState() restores selection and expansion state.
destroy() removes listeners, markup, and the root CSS class.
serializeStateToFragment(manifest) returns #v=1&c=...&x=... state.
restoreStateFromLocation(manifest, location) safely applies URL state.
validateManifest(manifest) reports unregistered and missing paths.

Options:

initiallyCollapsed defaults to true.
initiallySelected defaults to false.
storageKey defaults to null, which disables persistence.
onSelectionChange receives { selectedIds, selectedNodes }.
manifest optionally supplies a parsed manifest and automatically restores state from window.location.hash after setData().
stateEncoding selects "adaptive" (the default), "dense", or "tiered". The website's configured value is the URL-format contract and is not embedded in the fragment.

Shareable URL state

Create a JSON manifest whose array positions are permanent slots. Canonical node paths join ancestor IDs with >:

{ "schema": 1, "nodes": ["fruit", "fruit>apple", "fruit>pear", null] }

Import loadManifest, pass its result as the manifest option, and call tree.serializeStateToFragment() when creating a share link. Existing entries must never be reordered. Append new paths, replace removed paths with null, and edit a path in place for a logical rename or move. Node IDs therefore cannot contain >.

The fragment adaptively encodes checked (c) and expanded (x) state using the shortest of a dense bitset, sparse enabled slots, or sparse disabled slots. Sparse slot numbers are delta-encoded variable-length integers. A coverage value in the disabled-slot form ensures nodes appended later still default to unchecked and collapsed. Malformed or unsupported state is ignored. The helpers encodeTreeState, decodeTreeState, applyTreeState, and restoreStateFromLocation are also exported for custom integrations. Use validateManifestEvolution(previous, next) in a build check to reject removed slots and tombstone reuse; path changes are reported for deliberate rename/move review.

With stateEncoding: "tiered", c1 stores root checked state and each deeper cN field stores nodes whose checked state differs from their parent. Expansion does not inherit: every xN stores the actual expanded branches at that depth, with collapsed as the baseline. Each tier field uses the adaptive codec. The n field records manifest coverage so nodes appended later still default to false. A non-selectable parent supplies a false checked baseline. With stateEncoding: "dense", c and x contain trimmed least-significant-bit-first bitsets.

Styling is namespaced under .checkbox-tree. Override the custom properties --checkbox-tree-indent, --checkbox-tree-toggle-size, and --checkbox-tree-hover-color in the consuming application.

Development

npm install
npm test
npm run pack:check

Future demo ideas

Add population metadata to the country, state, and county nodes and display the total population represented by the current selection. Define the aggregation rule carefully so checked ancestors and their checked descendants are not counted twice; one option is to total only the most specific checked nodes.

5.0 KiB Raw Blame History