rat

react-accessible-treeview

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

Showing:

Popularity

Downloads/wk

602

GitHub Stars

20

Maintenance

Last Commit

2yrs ago

Contributors

2

Package

Dependencies

0

Size (min+gzip)

5.9KB

License

MIT

Type Definitions

Tree-Shakeable

Yes?

Categories

Readme

react-accessible-treeview Build Status Greenkeeper badge npm version License: MIT

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

Prop Types

Prop nameTypeDefault valueDescription
dataarray[node]requiredTree data
nodeRendererfuncrequiredRender prop for the node (see below for more details)
onSelectfuncnoopFunction called when a node changes its selected state
onExpandfuncnoopFunction called when a node changes its expanded state
classNamestring""className to add to the outermost dom element, al ul with role = "tree"
multiSelectboolfalseAllows multiple nodes to be selected
propagateSelectboolfalseIf set to true, selecting a node will also select its descendants
propagateSelectUpwardsboolfalseIf 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
propagateCollapseboolfalseIf set to true, collapsing a node will also collapse its descendants
expandOnKeyboardSelectboolfalseSelecting a node with a keyboard (using Space or Enter) will also toggle its expanded state
togglableSelectboolfalseWhether the selected state is togglable
defaultSelectedIdsarray[]Array with the ids of the default selected nodes
defaultExpandedIdsarray[]Array with the ids of the default expanded nodes
defaultDisabledIdsarray[]Array with the ids of the default disabled nodes
clickActionenumSELECTAction to perform on click. One of: EXCLUSIVE_SELECT, FOCUS, SELECT
onBlurfuncnoopCustom 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:

PropertyTypeDefaultDescription
idnumberrequiredA nonnegative integer that uniquely identifies the node
namestringrequiredUsed to match on key press
childrenarray[id]requiredAn array with the ids of the children nodes.
parentidrequiredThe parent of the node. null for the root node

The first item 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).



nodeRenderer

  • Arguments: An object containing the following properties:
PropertyTypeDescription
elementobjectThe object that represents the rendered node
getNodePropsfunctionA function which gives back the props to pass to the node
isBranchboolWhether the rendered node is a branch node
isSelectedboolWhether the rendered node is selected
isHalfSelectedbool or undefinedIf the node is a branch node, whether it is half-selected, else undefined
isExpandedbool or undefinedIf the node is a branch node, whether it is expanded, else undefined
isDisabledboolWhether the rendered node is disabled
levelnumberA positive integer that corresponds to the aria-level attribute
setsizenumberA positive integer that corresponds to the aria-setsize attribute
posinsetnumberA positive integer that corresponds to the aria-posinset attribute
handleSelectfunctionFunction to assign to the onClick event handler of the element(s) that will toggle the selected state
handleExpandfunctionFunction to assign to the onClick event handler of the element(s) that will toggle the expanded state
dispatchfunctionFunction to dispatch actions
treeStatefunctionstate of the treeview



onSelect

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

onExpand

  • Arguments: onExpand({element, isExpanded, isSelected, isHalfSelected, isDisabled, treeState}) Note: the function uses the state after the 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.

KeyFunction
Enter or SpaceUpdates 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.
HomeMoves focus to first node without opening or closing a node.
EndMoves 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 ArrowMoves focus to and toggles the selection state of the next node.
Shift + Up ArrowMoves focus to and toggles the selection state of the previous node.
Ctrl + ASelects all nodes in the tree. If all nodes are selected, unselects all nodes.



Mouse Navigation

KeyFunction
ClickToggles parent nodes and also performs one of clickActions = SELECT, EXCLUSIVE_SELECT, FOCUS
Ctrl+ClickIf 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+ClickIf 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

VariantFunction
SELECTSelects the clicked node (default).
EXCLUSIVE_SELECTSelects the clicked node and deselects the rest.
FOCUSFocuses the clicked node



treeState

The internal state of the component.

PropertyTypeDefaultDescription
selectedIdsSetnew Set(defaultSelectedIds)Set of the ids of the selected nodes
tabbableIdnumberdata[0].children[0]Id of the node with tabindex = 0
isFocusedboolfalseWhether the tree has focus
expandedIdsSetnew Set(defaultExpandedIds)Set of the ids of the expanded nodes
halfSelectedIdsSetnew Set()Set of the ids of the selected nodes
lastUserSelectnumberdata[0].children[0]Last selection made directly by the user
lastInteractedWithnumber or nullnullLast node interacted with
disabledIdsSetnew Set(defaultDisabledIds)Set of the ids of the selected nodes

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100