Tree View Component

The tree view component displays hierarchical data in a collapsible tree structure. It provides three distinct interaction modes (default, selectable items, and checkboxes), supports asynchronous loading of child nodes, and integrates with PatternFly's collection management patterns. This page documents the architecture, usage patterns, and internal mechanisms of the tree view system.

For information about other navigation components like expandable groups, see Navigation and Tabs. For general collection management patterns, see Collection Management.

Component Architecture

The tree view system consists of two primary classes that form a parent-child relationship with recursive nesting capabilities.

Class Structure Diagram

Sources: components/src/main/java/org/patternfly/component/tree/TreeView.java78-430 components/src/main/java/org/patternfly/component/tree/TreeViewItem.java106-671

Tree View Types

The tree view supports three interaction modes defined by TreeViewType, each with distinct DOM structure and selection behavior.

Type Comparison

DOM Structure by Type

Sources: components/src/main/java/org/patternfly/component/tree/TreeViewItem.java495-571

Item Management and Collection Pattern

Tree view items follow the HasItems pattern, enabling recursive nesting where each TreeViewItem can contain child TreeViewItem instances.

Hierarchical Item Relationships

Key Fields and Methods

TreeView maintains:

• LinkedHashMap<String, TreeViewItem> items - Top-level items indexed by identifier
• TreeViewType type - Determines interaction mode and DOM structure
• Supplier<Element> icon and expandedIcon - Default icons for all items

TreeViewItem maintains:

• LinkedHashMap<String, TreeViewItem> items - Child items
• TreeViewItem parent - Reference to parent item (null for root-level)
• String identifier - Unique identifier within parent's collection
• Map<String, Object> data - Component context for arbitrary data storage
• AsyncStatus status - Tracks async loading state: static_, pending, resolved, rejected
• AsyncItems<TreeViewItem, TreeViewItem> asyncItems - Function returning Promise of child items

Sources: components/src/main/java/org/patternfly/component/tree/TreeView.java94-117 components/src/main/java/org/patternfly/component/tree/TreeViewItem.java139-185

DOM Construction and Lifecycle

Tree view items undergo a two-phase initialization: construction followed by DOM finalization when attached to the parent tree.

Lifecycle Phases

finishDOM Implementation

The finishDOM(TreeView tv) method at TreeViewItem.java481-603 performs the following:

1. Validates state: Checks if already finished or if parent TreeView is null
2. Creates type-specific elements: Builds nodeElement, toggleElement, and textElement based on tv.type
3. Nests DOM structure: Assembles content → node → container → toggle, text
4. Renders content: Applies stored text, icon, and expandedIcon
5. Recursively finalizes children: Calls finishDOM(tv) on all child items

Sources: components/src/main/java/org/patternfly/component/tree/TreeViewItem.java481-603

Asynchronous Loading Pattern

Tree view items support lazy loading of children via the AsyncItems pattern, enabling large hierarchies to load on-demand.

Async Loading State Machine

Loading Sequence

Key Methods

• add(AsyncItems<TreeViewItem, TreeViewItem> items) at TreeViewItem.java202-206: Sets status to pending and stores the async function
• load() at TreeViewItem.java346-384: Executes the async function and handles loading/error states
• reset() at TreeViewItem.java386-395: Clears resolved/rejected items and resets to pending state
• reload() at TreeViewItem.java397-406: Calls reset() then load(), preserving expansion state

Sources: components/src/main/java/org/patternfly/component/tree/TreeViewItem.java202-206 components/src/main/java/org/patternfly/component/tree/TreeViewItem.java346-406

Selection Behavior

Selection behavior varies by tree view type, with checkboxes supporting cascading selection and indeterminate states.

Selection Propagation for Checkboxes

Checkbox Selection Logic

The markSelected(TreeViewType type, boolean selected) method at TreeViewItem.java605-617 implements:

1. Set tabIndex: Selected item gets tabIndex=0, others get tabIndex=-1
2. Apply visual modifier: For selectable types, toggle .pf-m-current class
3. Checkbox cascade:
   • Calls check(this, selected) which recursively sets all descendant checkboxes
   • Calls indeterminate(parent) which walks up the tree, setting parent checkboxes to:
     • checked if all children are checked
     • indeterminate if some (but not all) children are checked
     • unchecked if no children are checked

Sources: components/src/main/java/org/patternfly/component/tree/TreeViewItem.java605-653

Selection API

TreeView methods:

• select(String identifier) / select(TreeViewItem item) at TreeView.java251-290
• select(TreeViewItem item, boolean selected, boolean fireEvent) - For default_ and selectableItems types, unselects all other items first (single selection)
• selectedItems() at TreeView.java292-300 - Returns list of all selected items by traversing the tree
• unselect() / unselect(boolean fireEvent) at TreeView.java302-308 - Deselects all items

TreeViewItem methods:

• selected() at TreeViewItem.java307-314 - Returns selection state based on checkbox checked state or .pf-m-current modifier presence

Sources: components/src/main/java/org/patternfly/component/tree/TreeView.java251-308 components/src/main/java/org/patternfly/component/tree/TreeViewItem.java307-314

Expansion and Collapse

Tree view items implement the Expandable interface, controlling visibility of child items and icon state.

Expansion Mechanics

Toggle Element Visibility

The toggle element (chevron icon) is conditionally shown based on async status and item count:

Sources: components/src/main/java/org/patternfly/component/tree/TreeViewItem.java316-344 components/src/main/java/org/patternfly/component/tree/TreeViewItem.java577-579 components/src/main/java/org/patternfly/component/tree/TreeViewItem.java365-368

Event Handling and Navigation

The tree view supports multiple event handlers for item lifecycle, selection, and expansion.

Event Handler Types

Event Flow for Selection

Sources: components/src/main/java/org/patternfly/component/tree/TreeViewItem.java495-571 components/src/main/java/org/patternfly/component/tree/TreeView.java263-289

Tree Traversal Utilities

The static traverseItems(HasItems<?, ?, TreeViewItem> items, Consumer<TreeViewItem> code) method at TreeView.java382-387 recursively visits all items in the tree, enabling operations like:

• Finding all selected items (selectedItems())
• Resetting async state across the tree (reset())
• Unmarking all items (unselect())
• Custom traversal operations via consumer parameter

Sources: components/src/main/java/org/patternfly/component/tree/TreeView.java382-387

Keyboard Navigation

Keyboard navigation is registered in the attach() lifecycle method at TreeView.java120-140 and routes to type-specific handlers.

Navigation Handlers

• handleKeys(KeyboardEvent event) at TreeView.java415-421 - For default_ type
• handleKeysSelectable(KeyboardEvent event) at TreeView.java423-429 - For selectableItems and checkboxes types

Both handlers check that the event target has the .pf-v6-c-tree-view__node class before processing.

Note: The keyboard navigation implementation appears incomplete in the current codebase, as the handler methods contain only target validation without key-specific logic.

Sources: components/src/main/java/org/patternfly/component/tree/TreeView.java120-147 components/src/main/java/org/patternfly/component/tree/TreeView.java415-429

Component Context and Icons

Tree view items support custom data storage and flexible icon configuration.

Component Context Storage

TreeViewItem implements ComponentContext<HTMLLIElement, TreeViewItem>, providing:

• store(String key, T value) at TreeViewItem.java264-267 - Stores arbitrary data
• has(String key) at TreeViewItem.java413-415 - Checks if key exists
• get(String key) at TreeViewItem.java418-423 - Retrieves stored value

This enables associating domain objects or metadata with tree items without subclassing.

Icon Configuration Hierarchy

Icons are applied in finishDOM() at TreeViewItem.java586-595:

1. If item has specific icon, use it; otherwise call tv.icon.get()
2. If item has specific expandedIcon, use it; otherwise call tv.expandedIcon.get()
3. Icons are swapped on expand/collapse at TreeViewItem.java321-323 and TreeViewItem.java337-339

Sources: components/src/main/java/org/patternfly/component/tree/TreeViewItem.java231-261 components/src/main/java/org/patternfly/component/tree/TreeViewItem.java264-267 components/src/main/java/org/patternfly/component/tree/TreeViewItem.java413-423 components/src/main/java/org/patternfly/component/tree/TreeViewItem.java586-595