react-accessible-treeview

react-accessible-treeview implements the WAI-ARIA Authoring Practices treeview pattern as a React component, giving developers a hierarchical navigation or selection widget that is keyboard-operable and screen-reader friendly out of the box. Rather than shipping fixed markup, it exposes a nodeRenderer render prop and a getNodeProps prop-getter so consumers control every DOM element and class name while the library manages ARIA attributes (aria-level, aria-setsize, aria-posinset, aria-expanded, aria-selected) and focus behavior.

The component supports single and multi-select, disabled nodes, controlled and uncontrolled selection/expansion state, async on-demand loading of child nodes via onLoadData, and selection propagation to parents or descendants. A flattenTree helper converts a nested object into the flat {id, name, children, parent} array the component expects, and a full keyboard map (arrow keys, Home/End, type-ahead search, * to expand siblings, Shift+Arrow range selection, Ctrl+A select-all) follows the WAI-ARIA treeview-1b reference implementation.

What You Get

• A TreeView component with data, nodeRenderer, onSelect, onExpand, onNodeSelect, and onLoadData props covering the full lifecycle of tree interaction
• A flattenTree utility that converts nested tree objects into the flat, ID-referenced array structure the component consumes, preserving arbitrary metadata
• Full WAI-ARIA keyboard interaction support (arrow keys, Home/End, type-ahead, * expand-siblings, Shift+Arrow range select, Ctrl+A select-all) matching the W3C treeview-1b reference example
• Controlled and uncontrolled modes for both selectedIds and expandedIds, with defaultSelectedIds/defaultExpandedIds/defaultDisabledIds for uncontrolled use
• Configurable click behavior via clickAction (SELECT, EXCLUSIVE_SELECT, FOCUS) plus propagateSelect, propagateSelectUpwards, and propagateCollapse flags for parent/child selection cascades
• Async data loading support through onLoadData and the isBranch node flag, for trees whose children are fetched on expand rather than provided upfront

Common Use Cases

• File/folder explorers where users navigate directory structures with the keyboard and mouse
• Multi-select checkbox trees for permission or category pickers where selecting a parent should cascade to children
• Async-loaded organizational or category trees where child nodes are fetched from an API only when a branch is expanded
• Accessible navigation sidebars requiring full WAI-ARIA treeview keyboard support for compliance with accessibility audits
• Filterable or searchable tree UIs built on top of flattenTree, since consumers fully control node markup via nodeRenderer

Under The Hood

Architecture The library centers on a single useTree hook (src/TreeView/index.tsx) that drives a useReducer-based state machine (treeReducer in src/TreeView/reducer.ts) tracking selectedIds, expandedIds, disabledIds, halfSelectedIds, and focus/tabbable state as a discriminated-union action set. TreeView itself composes this hook with a recursive Node/branch renderer (src/TreeView/node.tsx) that calls back into the consumer’s nodeRenderer render prop for all markup, while the library computes ARIA attributes, refs (nodeRefs/leafRefs), and keyboard/focus behavior in utils.ts. Controlled vs. uncontrolled state is resolved by diffing incoming controlledSelectedIds/controlledExpandedIds against previous props (usePrevious, usePreviousData), which keeps the reducer as the single source of truth even when the parent drives selection externally.

Tech Stack Written in TypeScript (70% of the codebase) with a small JavaScript/CSS/MDX surface for the Storybook and Docusaurus website, it depends only on classnames and prop-types as runtime peers alongside react/react-dom (16.8-19 supported via peerDependencies). The library is bundled with Rollup (CJS + ESM outputs, rollup-plugin-typescript2) and typechecked with a standalone tsc --noEmit script; the docs/demo site is a separate Docusaurus app under website/ deployed to GitHub Pages.

Code Quality Testing uses Jest with @testing-library/react and jest-environment-jsdom, and the suite is extensive relative to the library’s size — 16 test files under src/__tests__/ covering controlled/uncontrolled selection, multi-select checkbox trees (sync and async, controlled and uncontrolled), directory-tree examples, node IDs, metadata passthrough, and tree-data validation. ESLint (with eslint-plugin-jsx-a11y and eslint-plugin-react-hooks) and a type-check script both run in CI (pr-gate.yml) alongside npm test and a production build, so lint/type/test regressions are caught pre-merge. Naming is consistent (I-prefixed interfaces, action-type unions) though some reducer action shapes carry loosely-typed optional flags (e.g. NotUserAction?: boolean).

API Design The public surface is a single default-exported TreeView component plus named exports (flattenTree, INode, CLICK_ACTIONS, prop/state types) re-exported from src/index.ts, keeping the import surface small and typed end-to-end. Getting started requires building the flat {id, name, children, parent} data shape (or calling flattenTree on a nested object) and supplying a nodeRenderer render prop — more setup than a batteries-included component, but it buys full control over markup, which the extensive Docusaurus example set (a dozen-plus documented recipes: async loading, controlled focus, disabled nodes, filtering, directory trees) is clearly designed to offset.