SEEKING NEW MAINTAINERS

We're looking to give this repository to a new owner. Please see issue https://github.com/dgreene1/react-accessible-treeview/issues/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.

$3

- 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.

$3

- 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:

``js static
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 |