React-accessible-treeview NPM

react-accessible-treeview

A react component that implements the treeview pattern as described by the WAI-ARIA Authoring Practices.

Features

Single and multiple selection.
Disabled nodes.
Extensive key bindings.
Highly customizable through the use of the render prop and prop getter patterns.
WAI-ARIA compliant.

Documentation and Demo

https://dgreene1.github.io/react-accessible-treeview

Prop Types

Prop name	Type	Default value	Description
`data`	`array[node]`	`required`	Tree data
`nodeRenderer`	`func`	`required`	Render prop for the node (see below for more details)
`onSelect`	`func`	`noop`	Function called when a node changes its selected state
`onNodeSelect`	`func`	`noop`	Function called when a node was manually selected/deselected
`onExpand`	`func`	`noop`	Function called when a node changes its expanded state
`className`	`string`	`""`	className to add to the outermost dom element, al `ul` with `role = "tree"`
`multiSelect`	`bool`	`false`	Allows multiple nodes to be selected
`propagateSelect`	`bool`	`false`	If set to true, selecting a node will also select its descendants
`propagateSelectUpwards`	`bool`	`false`	If set to true, selecting a node will update the state of its parent (e.g. a parent node in a checkbox will be automatically selected if all of its children are selected
`propagateCollapse`	`bool`	`false`	If set to true, collapsing a node will also collapse its descendants
`expandOnKeyboardSelect`	`bool`	`false`	Selecting a node with a keyboard (using Space or Enter) will also toggle its expanded state
`togglableSelect`	`bool`	`false`	Whether the selected state is togglable
`defaultSelectedIds`	`array`	`[]`	Array with the ids of the default selected nodes
`defaultExpandedIds`	`array`	`[]`	Array with the ids of the default expanded nodes
`defaultDisabledIds`	`array`	`[]`	Array with the ids of the default disabled nodes
`selectedIds`	`array`	`[]`	(Controlled) Array with the ids that should be selected
`expandedIds`	`array`	`[]`	(Controlled) Array with the ids of branch node that should be expanded
`clickAction`	`enum`	`SELECT`	Action to perform on click. One of: EXCLUSIVE_SELECT, FOCUS, SELECT
`onBlur`	`func`	`noop`	Custom onBlur event that is triggered when focusing out of the component as a whole (moving focus between the nodes won't trigger it).

data

An array of nodes. Nodes are objects with the following structure:

Property	Type	Default	Description
`id`	`number` or `string`	required	A nonnegative integer or string that uniquely identifies the node
`name`	`string`	required	Used to match on key press
`children`	`array[id]`	required	An array with the ids of the children nodes.
`parent`	`id`	required	The parent of the node. `null` for the root node
`isBranch`	`boolean`	optional	Used to indicated whether a node is branch to be able load async data onExpand, default is false
`metadata`	`object`	optional	Used to add metadata into node object. We do not currently support metadata that is a nested object

The item with parent:null of the array represents the root node and won't be displayed.

Example:

const data = [
  { name: "", children: [1, 4, 9, 10, 11], id: 0, parent: null },
  { name: "src", children: [2, 3], id: 1, parent: 0 },
  { name: "index.js", id: 2, parent: 1 },
  { name: "styles.css", id: 3, parent: 1 },
  { name: "node_modules", children: [5, 7], id: 4, parent: 0 },
  { name: "react-accessible-treeview", children: [6], id: 5, parent: 4 },
  { name: "bundle.js", id: 6, parent: 5 },
  { name: "react", children: [8], id: 7, parent: 4 },
  { name: "bundle.js", id: 8, parent: 7 },
  { name: ".npmignore", id: 9, parent: 0 },
  { name: "package.json", id: 10, parent: 0 },
  { name: "webpack.config.js", id: 11, parent: 0 },
];

The array can also be generated from a nested object using the flattenTree helper (see the examples below). flattenTree preserves metadata.

Data supports non-sequential ids provided by user.

nodeRenderer

Arguments: An object containing the following properties:

Property	Type	Description
`element`	`object`	The object that represents the rendered node
`getNodeProps`	`function`	A function which gives back the props to pass to the node
`isBranch`	`bool`	Whether the rendered node is a branch node
`isSelected`	`bool`	Whether the rendered node is selected
`isHalfSelected`	`bool` or `undefined`	If the node is a branch node, whether it is half-selected, else undefined
`isExpanded`	`bool` or `undefined`	If the node is a branch node, whether it is expanded, else undefined
`isDisabled`	`bool`	Whether the rendered node is disabled
`level`	`number`	A positive integer that corresponds to the aria-level attribute
`setsize`	`number`	A positive integer that corresponds to the aria-setsize attribute
`posinset`	`number`	A positive integer that corresponds to the aria-posinset attribute
`handleSelect`	`function`	Function to assign to the onClick event handler of the element(s) that will toggle the selected state
`handleExpand`	`function`	Function to assign to the onClick event handler of the element(s) that will toggle the expanded state
`dispatch`	`function`	Function to dispatch actions
`treeState`	`object`	state of the treeview

onSelect

Arguments: onSelect({element, isBranch, isExpanded, isSelected, isHalfSelected, isDisabled, treeState }) Note: the function uses the state after the selection.

onNodeSelect

Arguments: onNodeSelect({element, isBranch, isSelected, treeState }) Note: the function uses the state right after the selection before propagation.

onExpand

Arguments: onExpand({element, isExpanded, isSelected, isHalfSelected, isDisabled, treeState}) Note: the function uses the state after the expansion.

onLoadData

Arguments: onLoadData({element, isExpanded, isSelected, isHalfSelected, isDisabled, treeState}) Note: the function uses the state after inital data is loaded and on expansion.

Keyboard Navigation

Follows the same conventions described in https://www.w3.org/TR/wai-aria-practices/examples/treeview/treeview-1/treeview-1b.html and https://www.w3.org/TR/wai-aria-practices/#keyboard-interaction-22.

Key	Function
`Enter` or `Space`	Updates the selected node to the current node and triggers `onSelect`
`Down Arrow`	Moves focus to the next node that is tabbable without opening or closing a node. If focus is on the last node, does nothing.
`Up arrow`	Moves focus to the previous node that is tabbable without opening or closing a node. If focus is on the first node, does nothing.
`Right Arrow`	When focus is on a closed node, opens the node; focus does not move. When focus is on an end node, does nothing. When focus is on a open node, moves focus to the first child node.
`Left Arrow`	When focus is on an open node, closes the node. When focus is on a child node that is also either an end node or a closed node, moves focus to its parent node. When focus is on a root node that is also either an end node or a closed node, does nothing.
`Home`	Moves focus to first node without opening or closing a node.
`End`	Moves focus to the last node that can be focused without expanding any nodes that are closed.
`a-z, A-Z`	Focus moves to the next node with a name that starts with the typed character. Search wraps to first node if a matching name is not found among the nodes that follow the focused node. Search ignores nodes that are descendants of closed nodes.
`*` (asterisk)	Expands all closed sibling nodes that are at the same level as the focused node. Focus does not move.
`Shift + Down Arrow`	Moves focus to and toggles the selection state of the next node.
`Shift + Up Arrow`	Moves focus to and toggles the selection state of the previous node.
`Ctrl + A`	Selects all nodes in the tree. If all nodes are selected, unselects all nodes.

Mouse Navigation

Key	Function
`Click`	Toggles parent nodes and also performs one of `clickActions = SELECT, EXCLUSIVE_SELECT, FOCUS`
`Ctrl+Click`	If `multiselect` is set to `true`, selects the node without dropping the current selected ones. If false, it selects the clicked node. Doesn't toggle parents.
`Shift+Click`	If `multiselect` is set to `true`, selects from the node without dropping the current selected ones. If false, it focus the clicked node. Doesn't toggle parents.

Click actions

Variant	Function
`SELECT`	Selects the clicked node (default).
`EXCLUSIVE_SELECT`	Selects the clicked node and deselects the rest.
`FOCUS`	Focuses the clicked node

treeState

The internal state of the component.

Property	Type	Default	Description
selectedIds	`Set`	`new Set(defaultSelectedIds)`	Set of the ids of the selected nodes
controlledIds	`Set`	`new Set(controlledSelectedIds)`	Set of the ids of the nodes selected programmatically
tabbableId	`number`	`data[0].children[0]`	Id of the node with tabindex = 0
isFocused	`bool`	`false`	Whether the tree has focus
expandedIds	`Set`	`new Set(defaultExpandedIds)`	Set of the ids of the expanded nodes
halfSelectedIds	`Set`	`new Set()`	Set of the ids of the selected nodes
lastUserSelect	`number`	`data[0].children[0]`	Last selection made directly by the user
lastInteractedWith	`number or null`	`null`	Last node interacted with
lastManuallyToggled	`number or null`	`null`	Last node that was manually selected/deselected
disabledIds	`Set`	`new Set(defaultDisabledIds)`	Set of the ids of the selected nodes