useTree

Usage#

import { useTree, useTreeNode } from '@primereact/headless/tree';
 
const tree = useTree({ value: nodes, selectionMode: 'single' });
const { rootProps } = tree;
 
const treeNode = useTreeNode({ node: nodes[0], context: tree, index: 0 });
const { state, nodeProps, contentProps } = treeNode;
const toggleProps = tree.getToggleProps(nodes[0]);
 
return (
    <div {...rootProps}>
        <ul {...tree.getListProps(false)}>
            <li {...nodeProps}>
                <div {...contentProps}>
                    <button {...toggleProps}></button>
                </div>
            </li>
        </ul>
    </div>
);

useTree manages root state while useTreeNode consumes that context to return prop objects for each node element — see Primitive for a component-based API.

Features#

• Two-hook architecture: useTree for root state, useTreeNode for per-node behavior
• Returns spread-ready prop objects via rootProps, getNodeProps, getToggleProps, getListProps, filterProps
• Three selection modes: single, multiple, checkbox with parent-child propagation
• Controlled and uncontrolled expansion and selection state
• Built-in drag-drop with scope validation for same-tree and cross-tree transfers
• Typeahead search across visible nodes

Behavior#

Default Expanded Keys#

Use defaultExpandedKeys to set initially expanded nodes. Keys are a Record<string, boolean>.

const tree = useTree({ value: nodes, defaultExpandedKeys: { '0': true, '1': true } });

Controlled Expansion#

Use expandedKeys and onExpandedChange for full programmatic control.

const [expandedKeys, setExpandedKeys] = React.useState<TreeExpandedKeys>({ '0': true });
const tree = useTree({
    value: nodes,
    expandedKeys,
    onExpandedChange: (e) => setExpandedKeys(e.value)
});

Selection Mode#

Set selectionMode to single, multiple, or checkbox. Use selectionKeys and onSelectionChange for controlled selection.

const tree = useTree({ value: nodes, selectionMode: 'single' });

In checkbox mode, selection keys use { checked: boolean, partialChecked: boolean } shape. Parent-child propagation is handled automatically.

Meta Key Selection#

In multiple mode, metaKeySelection controls whether the meta key (Cmd/Ctrl) is required to add to existing selections. Defaults to true.

const tree = useTree({ value: nodes, selectionMode: 'multiple', metaKeySelection: false });

Drag and Drop#

Enable drag-drop by setting draggableNodes and droppableNodes. Use draggableScope and droppableScope to restrict transfers between trees.

const tree = useTree({
    value: nodes,
    draggableNodes: true,
    droppableNodes: true,
    onValueChange: (e) => setNodes(e.value)
});

Filtering#

Spread filterProps on an input element to enable search filtering. The hook provides autoComplete: 'off' and keyboard handling.

<input {...tree.filterProps} />

Conditional Rendering with state.expanded#

Use state.expanded from useTreeNode to conditionally render child nodes.

const { state } = useTreeNode({ node, context: tree, index: 0 });
 
{
    state.expanded && node.children && (
        <ul {...tree.getListProps(true)}>
            {node.children.map((child, i) => (
                <TreeNodeItem key={child.key} node={child} index={i} />
            ))}
        </ul>
    );
}

Custom Styling with Data Attributes#

Every prop object includes data-scope="tree" and a data-part attribute. State-dependent attributes are added automatically to enable CSS-only styling.

rootProps#

nodeProps#

contentProps#

getToggleProps#

dropPointProps#

[data-scope='tree'][data-part='content'] {
    padding: 0.25rem 0.5rem;
}
 
[data-scope='tree'][data-part='content'][data-selected] {
    background-color: rgba(var(--primary-rgb), 0.1);
}
 
[data-scope='tree'][data-part='content'][data-expanded] {
    font-weight: 600;
}
 
[data-scope='tree'][data-part='node'][data-node-key='0'] {
    font-weight: bold;
}

API#

useTree#

useTreeNode#

Accessibility#

See Tree Primitive for WAI-ARIA compliance details and keyboard support.