SEEKING NEW MAINTAINERS

We're looking to give this repository to a new owner. Please see issue dgreene1#222 to inquire about being the new owner.

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. Unused if selectedIds is provided.
defaultExpandedIds	array	[]	Array with the ids of the default expanded nodes. Unused if expandedIds is provided.
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