@zendeskgarden/container-treeview
This package includes containers relating to Treeview in the Garden Design System.
This package offers a headless implementation to W3C TreeView Design Pattern and offers accessible navigation
WAI-ARIA support
For a vertically oriented tree (horizontal and RTL are supported as well):
Keyboard interactions
- When a single-select tree receives focus:
- If none of the nodes are selected before the tree receives focus, focus is set on the first node.
- If a node is selected before the tree receives focus, focus is set on the selected node.
❌ When a multi-select tree receives focus:- If none of the nodes are selected before the tree receives focus, focus is set on the first node.
- If one or more nodes are selected before the tree receives focus, focus is set on the first selected node.
✅ Right arrow
:- When focus is on a closed node, opens the node; focus does not move.
- When focus is on a open node, moves focus to the first child node.
- When focus is on an end node, does nothing.
✅ 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.
✅ Down Arrow
: Moves focus to the next node that is focusable without opening or closing a node.✅ Up Arrow
: Moves focus to the previous node that is focusable without opening or closing a node.✅ Home
: Moves focus to the first node in the tree without opening or closing a node.✅ End
: Moves focus to the last node in the tree that is focusable without opening a node.✅ Enter
: activates a node, i.e., performs its default action. For parent nodes, one possible default action is to open or close the node. In single-select trees where selection does not follow focus (see note below), the default action is typically to select the focused node.❌ Type-ahead is recommended for all trees, especially for trees with more than 7 root nodes:- Type a character: focus moves to the next node with a name that starts with the typed character.
- Type multiple characters in rapid succession: focus moves to the next node with a name that starts with the string of characters typed.
❌ *
(Optional): Expands all siblings that are at the same level as the current node.❌ Selection in multi-select trees:
WAI-ARIA Roles, States, and Properties
✅ All tree nodes are contained in or owned by an element with roletree
.✅ Each element serving as atree
node has roletreeitem
.✅ Each root node is contained in the element with roletree
or❌ ❓ referenced by anaria-owns
property set on thetree
element.✅ Each parent node contains or owns an element with rolegroup
.✅ Each child node is contained in or owned by an element with rolegroup
that is contained in or owned by the node that serves as the parent of that child.✅ Each element with roletreeitem
that serves as a parent node hasaria-expanded
set to false when the node is in a closed state and set to true when the node is in an open state. End nodes do not have thearia-expanded
attribute because, if they were to have it, they would be incorrectly described to assistive technologies as parent nodes.❌ Thetree
role supports the aria-activedescendant property, which provides an alternative to moving DOM focus amongtreeitem
elements when implementing keyboard navigation.❌ If thetree
supports selection of more than one node, the element with roletree
hasaria-multiselectable
set to true. Otherwise,aria-multiselectable
is either set to false or the default value of false is implied.❌ If thetree
does not support multiple selection,aria-selected
is set to true for the selected node and it is not present on any other node in the tree.❌ if thetree
supports multiple selection:- All selected nodes have
aria-selected
set to true. - All nodes that are selectable but not selected have
aria-selected
set to false. - If the
tree
contains nodes that are not selectable, those nodes do not have thearia-selected
state.
- All selected nodes have
✅ ❓ The element with roletree
has either a visible label referenced byaria-labelledby
or a value specified foraria-label
.❌ If the complete set of available nodes is not present in the DOM due to dynamic loading as the user moves focus in or scrolls the tree, each node hasaria-level
,aria-setsize
, andaria-posinset
specified.✅ If thetree
element is horizontally oriented, it hasaria-orientation
set tohorizontal
. The default value ofaria-orientation
for a tree isvertical
.
Installation
npm install @zendeskgarden/container-treeview
Usage
Check out storybook for live examples.
useTreeview
import { useTreeview } from '@zendeskgarden/container-treeview';
const Treeview = () => {
const { getTreeviewProps } = useTreeview();
return <div {...getTreeviewProps()} />;
};
TreeviewContainer
import { TreeviewContainer } from '@zendeskgarden/container-treeview';
<TreeviewContainer>{({ getTreeviewProps }) => <div {...getTreeviewProps()} />}</TreeviewContainer>;