Tree View Component

Relevant source files

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

Type	Selection Mechanism	Toggle Behavior	Use Case
`default_`	Click node to select and toggle	Single click for both	Simple navigation trees
`selectableItems`	Separate toggle button and text button	Independent toggle/select	Trees with actions on items
`checkboxes`	Checkbox for selection, button for toggle	Multi-select with cascading	Forms with hierarchical choices

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:

Validates state: Checks if already finished or if parent TreeView is null
Creates type-specific elements: Builds nodeElement, toggleElement, and textElement based on tv.type
Nests DOM structure: Assembles content node container toggle, text
Renders content: Applies stored text, icon, and expandedIcon
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:

Set tabIndex: Selected item gets tabIndex=0, others get tabIndex=-1
Apply visual modifier: For selectable types, toggle .pf-m-current class
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

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

Event Handler Types

Handler	Scope	Purpose	Method Signature
`AddItemHandler`	TreeView, TreeViewItem	Fired when item added	`onAdd(TreeView/TreeViewItem, TreeViewItem)`
`UpdateItemHandler`	TreeView, TreeViewItem	Fired when item updated	`onUpdate(TreeView/TreeViewItem, old, new)`
`RemoveItemHandler`	TreeView, TreeViewItem	Fired when item removed	`onRemove(TreeView/TreeViewItem, TreeViewItem)`
`ToggleHandler`	TreeView, TreeViewItem	Fired on expand/collapse	`onToggle(Event, TreeViewItem, boolean)`
`SelectHandler`	TreeView	Fired on item selection (single)	`onSelect(Event, TreeViewItem, boolean)`
`MultiSelectHandler`	TreeView	Fired on selection change (multi)	`onSelect(Event, TreeView, List<TreeViewItem>)`

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 is registered in the attach() lifecycle method at TreeView.java120-140 and routes to type-specific 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:

If item has specific icon, use it; otherwise call tv.icon.get()
If item has specific expandedIcon, use it; otherwise call tv.expandedIcon.get()
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