Tree<T> class

A comprehensive tree widget with hierarchical data display and interaction.

Tree provides a scrollable tree interface that displays hierarchical data with support for expansion/collapse, multi-selection, keyboard navigation, and visual branch lines. It handles complex tree operations like recursive selection, range selection, and immutable state updates.

The widget supports both mouse and keyboard interaction including:

Click to select items and toggle expansion
Ctrl+Click for multi-selection
Shift+Click for range selection
Arrow keys for navigation and selection
Space bar for selection toggle
Left/Right arrows for expand/collapse

Features:

Hierarchical data display with customizable branch lines
Single and multi-selection modes with recursive selection support
Keyboard navigation and accessibility
Scrollable content with shrink wrap support
Customizable expand icons and visual styling
Immutable state management with helper methods
Focus management and scope integration

The tree uses immutable data structures where all modifications return new instances. Helper methods and extensions provide convenient operations for common tree manipulations like expanding, selecting, and filtering nodes.

Every node (including descendants of a collapsed node) is built as a real widget, with collapsed subtrees animated down to zero size. This gives a smooth expand/collapse animation but means Tree builds a widget per node regardless of visibility. For very large or mostly-collapsed trees (e.g. a 50,000-file directory listing), use TreeView instead, which only builds nodes that are actually visible (at the cost of an instant, non-animated expand/collapse).

Example:

Tree<String>(
  nodes: [
    TreeItemNode(
      data: 'Documents',
      expanded: true,
      children: [
        TreeItemNode(data: 'document1.txt'),
        TreeItemNode(data: 'document2.txt'),
      ],
    ),
    TreeItemNode(data: 'Images'),
  ],
  builder: (context, item) => Text(item.data),
  onSelectionChanged: (selected, multiSelect, isSelected) {
    // Handle selection changes
  },
)

Inheritance

Available extensions

Constructors

Tree({Key? key, required List<TreeNode<T>> nodes, required Widget builder(BuildContext context, TreeItemNode<T> node), bool shrinkWrap = false, ScrollController? controller, BranchLine? branchLine, EdgeInsetsGeometry? padding, bool? expandIcon, bool? allowMultiSelect, FocusScopeNode? focusNode, TreeNodeSelectionChanged<T>? onSelectionChanged, bool? recursiveSelection}): Creates a Tree with hierarchical data display and interaction.
const

Properties

allowMultiSelect → bool?: Whether multiple tree nodes can be selected simultaneously.
final
asBuilder → NeverWidgetBuilder: Available on Widget, provided by the WidgetExtension extension
Converts this widget to a builder function.
no setter
base → TextModifier: Available on Widget, provided by the TextExtension extension
Applies base (default) font size.
no setter
black → TextModifier: Available on Widget, provided by the TextExtension extension
Applies black font weight (900).
no setter
blockQuote → TextModifier: Available on Widget, provided by the TextExtension extension
Applies block quote style with left border.
no setter
bold → TextModifier: Available on Widget, provided by the TextExtension extension
Applies bold font weight (700).
no setter
branchLine → BranchLine?: The style of branch lines connecting tree nodes.
final
builder → Widget Function(BuildContext context, TreeItemNode<T> node): Builder function to create widgets for tree items.
final
controller → ScrollController?: Optional scroll controller for the tree's scroll view.
final
ellipsis → TextModifier: Available on Widget, provided by the TextExtension extension
Applies ellipsis overflow to text.
no setter
expandIcon → bool?: Whether to show expand/collapse icons for nodes with children.
final
extraBold → TextModifier: Available on Widget, provided by the TextExtension extension
Applies extra-bold font weight (800).
no setter
extraLight → TextModifier: Available on Widget, provided by the TextExtension extension
Applies extra-light font weight (200).
no setter
firstP → TextModifier: Available on Widget, provided by the TextExtension extension
Applies paragraph style for the first paragraph (no top spacing).
no setter
focusNode → FocusScopeNode?: Optional focus scope node for keyboard navigation.
final
foreground → TextModifier: Available on Widget, provided by the TextExtension extension
Applies standard foreground color.
no setter
h1 → TextModifier: Available on Widget, provided by the TextExtension extension
Applies heading 1 style.
no setter
h2 → TextModifier: Available on Widget, provided by the TextExtension extension
Applies heading 2 style with bottom border.
no setter
h3 → TextModifier: Available on Widget, provided by the TextExtension extension
Applies heading 3 style.
no setter
h4 → TextModifier: Available on Widget, provided by the TextExtension extension
Applies heading 4 style.
no setter
hashCode → int: The hash code for this object.
no setterinherited
iconDestructiveForeground → WrappedIcon: Available on Widget, provided by the IconExtension extension
Wraps the icon with destructive foreground color.
no setter
iconLarge → WrappedIcon: Available on Widget, provided by the IconExtension extension
Wraps the icon with large size theme.
no setter
iconMedium → WrappedIcon: Available on Widget, provided by the IconExtension extension
Wraps the icon with medium size theme.
no setter
iconMutedForeground → WrappedIcon: Available on Widget, provided by the IconExtension extension
Wraps the icon with muted foreground color.
no setter
iconPrimary → WrappedIcon: Available on Widget, provided by the IconExtension extension
Wraps the icon with primary color.
no setter
iconPrimaryForeground → WrappedIcon: Available on Widget, provided by the IconExtension extension
Wraps the icon with primary foreground color.
no setter
iconSecondary → WrappedIcon: Available on Widget, provided by the IconExtension extension
Wraps the icon with secondary color.
no setter
iconSecondaryForeground → WrappedIcon: Available on Widget, provided by the IconExtension extension
Wraps the icon with secondary foreground color.
no setter
iconSmall → WrappedIcon: Available on Widget, provided by the IconExtension extension
Wraps the icon with small size theme.
no setter
iconX2Large → WrappedIcon: Available on Widget, provided by the IconExtension extension
Wraps the icon with extra-extra large size theme.
no setter
iconX2Small → WrappedIcon: Available on Widget, provided by the IconExtension extension
Wraps the icon with extra-extra small size theme.
no setter
iconX3Large → WrappedIcon: Available on Widget, provided by the IconExtension extension
Wraps the icon with extra-extra-extra large size theme.
no setter
iconX3Small → WrappedIcon: Available on Widget, provided by the IconExtension extension
Wraps the icon with extra-extra-extra small size theme.
no setter
iconX4Large → WrappedIcon: Available on Widget, provided by the IconExtension extension
Wraps the icon with extra-extra-extra-extra large size theme.
no setter
iconX4Small → WrappedIcon: Available on Widget, provided by the IconExtension extension
Wraps the icon with extra-extra-extra-extra small size theme.
no setter
iconXLarge → WrappedIcon: Available on Widget, provided by the IconExtension extension
Wraps the icon with extra large size theme.
no setter
iconXSmall → WrappedIcon: Available on Widget, provided by the IconExtension extension
Wraps the icon with extra small size theme.
no setter
inlineCode → TextModifier: Available on Widget, provided by the TextExtension extension
Applies inline code style with background and padding.
no setter
italic → TextModifier: Available on Widget, provided by the TextExtension extension
Applies italic font style.
no setter
key → Key?: Controls how one widget replaces another widget in the tree.
finalinherited
large → TextModifier: Available on Widget, provided by the TextExtension extension
Applies large font size.
no setter
lead → TextModifier: Available on Widget, provided by the TextExtension extension
Applies lead paragraph style with muted color.
no setter
li → TextModifier: Available on Widget, provided by the TextExtension extension
Applies list item style with bullet point.
no setter
light → TextModifier: Available on Widget, provided by the TextExtension extension
Applies light font weight (300).
no setter
medium → TextModifier: Available on Widget, provided by the TextExtension extension
Applies medium font weight (500).
no setter
modify → TextModifier: Available on Widget, provided by the TextExtension extension
Applies primary foreground color modifier.
no setter
mono → TextModifier: Available on Widget, provided by the TextExtension extension
Applies monospace font family.
no setter
muted → TextModifier: Available on Widget, provided by the TextExtension extension
Applies muted foreground color.
no setter
nodes → List<TreeNode<T>>: List of tree nodes to display in the tree view.
final
normal → TextModifier: Available on Widget, provided by the TextExtension extension
Applies normal font weight (400).
no setter
onSelectionChanged → TreeNodeSelectionChanged<T>?: Callback invoked when node selection changes.
final
p → TextModifier: Available on Widget, provided by the TextExtension extension
Applies paragraph style with top spacing.
no setter
padding → EdgeInsetsGeometry?: Padding around the tree view content.
final
primaryForeground → TextModifier: Available on Widget, provided by the TextExtension extension
Applies primary foreground color.
no setter
recursiveSelection → bool?: Whether selecting a parent node also selects its children.
final
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
sans → TextModifier: Available on Widget, provided by the TextExtension extension
Applies sans-serif font family.
no setter
secondaryForeground → TextModifier: Available on Widget, provided by the TextExtension extension
Applies secondary foreground color.
no setter
semiBold → TextModifier: Available on Widget, provided by the TextExtension extension
Applies semi-bold font weight (600).
no setter
shrinkWrap → bool: Whether the tree view should size itself to its content.
final
singleLine → TextModifier: Available on Widget, provided by the TextExtension extension
Constrains text to a single line without wrapping.
no setter
small → TextModifier: Available on Widget, provided by the TextExtension extension
Applies small font size.
no setter
textCenter → TextModifier: Available on Widget, provided by the TextExtension extension
Centers text horizontally.
no setter
textEnd → TextModifier: Available on Widget, provided by the TextExtension extension
Aligns text to the end (right in LTR, left in RTL).
no setter
textJustify → TextModifier: Available on Widget, provided by the TextExtension extension
Justifies text alignment.
no setter
textLarge → TextModifier: Available on Widget, provided by the TextExtension extension
Applies large text style.
no setter
textLeft → TextModifier: Available on Widget, provided by the TextExtension extension
Left-aligns text.
no setter
textMuted → TextModifier: Available on Widget, provided by the TextExtension extension
Applies muted text style with muted color.
no setter
textRight → TextModifier: Available on Widget, provided by the TextExtension extension
Right-aligns text.
no setter
textSmall → TextModifier: Available on Widget, provided by the TextExtension extension
Applies small text style.
no setter
textStart → TextModifier: Available on Widget, provided by the TextExtension extension
Aligns text to the start (left in LTR, right in RTL).
no setter
thin → TextModifier: Available on Widget, provided by the TextExtension extension
Applies thin font weight (100).
no setter
underline → TextModifier: Available on Widget, provided by the TextExtension extension
Applies underline text decoration.
no setter
x2Large → TextModifier: Available on Widget, provided by the TextExtension extension
Applies 2x large font size.
no setter
x3Large → TextModifier: Available on Widget, provided by the TextExtension extension
Applies 3x large font size.
no setter
x4Large → TextModifier: Available on Widget, provided by the TextExtension extension
Applies 4x large font size.
no setter
x5Large → TextModifier: Available on Widget, provided by the TextExtension extension
Applies 5x large font size.
no setter
x6Large → TextModifier: Available on Widget, provided by the TextExtension extension
Applies 6x large font size.
no setter
x7Large → TextModifier: Available on Widget, provided by the TextExtension extension
Applies 7x large font size.
no setter
x8Large → TextModifier: Available on Widget, provided by the TextExtension extension
Applies 8x large font size.
no setter
x9Large → TextModifier: Available on Widget, provided by the TextExtension extension
Applies 9x large font size.
no setter
xLarge → TextModifier: Available on Widget, provided by the TextExtension extension
Applies extra-large font size.
no setter
xSmall → TextModifier: Available on Widget, provided by the TextExtension extension
Applies extra-small font size.
no setter

Methods

asSkeleton({bool enabled = true, bool leaf = false, Widget? replacement, bool unite = false, AsyncSnapshot? snapshot}) → Widget: Available on Widget, provided by the SkeletonExtension extension
Converts the widget to a skeleton with advanced configuration options.
asSkeletonSliver({bool enabled = true}) → Widget: Available on Widget, provided by the SkeletonExtension extension
Converts the widget to a skeleton suitable for sliver layouts.
center({Key? key}) → Widget: Available on Widget, provided by the WidgetExtension extension
Centers this widget horizontally and vertically.
clip({Clip clipBehavior = Clip.hardEdge}) → Widget: Available on Widget, provided by the WidgetExtension extension
Clips this widget to a rectangle.
clipOval({Clip clipBehavior = Clip.antiAlias}) → Widget: Available on Widget, provided by the WidgetExtension extension
Clips this widget to an oval shape.
clipPath({Clip clipBehavior = Clip.antiAlias, required CustomClipper<Path> clipper}) → Widget: Available on Widget, provided by the WidgetExtension extension
Clips this widget to a custom path.
clipRRect({BorderRadiusGeometry borderRadius = BorderRadius.zero, Clip clipBehavior = Clip.antiAlias}) → Widget: Available on Widget, provided by the WidgetExtension extension
Clips this widget to a rounded rectangle.
constrained({double? minWidth, double? maxWidth, double? minHeight, double? maxHeight, double? width, double? height}) → Widget: Available on Widget, provided by the WidgetExtension extension
Wraps this widget in a ConstrainedBox with specified constraints.
createElement() → StatefulElement: Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → State<Tree<T>>: Creates the mutable state for this widget at a given location in the tree.
override
debugDescribeChildren() → List<DiagnosticsNode>: Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void: Add additional properties associated with the node.
inherited
excludeSkeleton({bool exclude = true}) → Widget: Available on Widget, provided by the SkeletonExtension extension
Controls whether the widget should be preserved in skeleton mode.
expanded({int flex = 1}) → Widget: Available on Widget, provided by the WidgetExtension extension
Makes this widget expanded within a Flex parent (Row/Column).
ignoreSkeleton() → Widget: Available on Widget, provided by the SkeletonExtension extension
Excludes the widget from skeleton effects in its parent skeleton context.
intrinsic({double? stepWidth, double? stepHeight}) → Widget: Available on Widget, provided by the WidgetExtension extension
Sizes this widget to both intrinsic width and height.
intrinsicHeight() → Widget: Available on Widget, provided by the WidgetExtension extension
Sizes this widget to its intrinsic height.
intrinsicWidth({double? stepWidth, double? stepHeight}) → Widget: Available on Widget, provided by the WidgetExtension extension
Sizes this widget to its intrinsic width.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
positioned({Key? key, double? left, double? top, double? right, double? bottom}) → Widget: Available on Widget, provided by the WidgetExtension extension
Positions this widget absolutely within a Stack.
sized({double? width, double? height, double? size}) → Widget: Available on Widget, provided by the WidgetExtension extension
Wraps this widget in a SizedBox with specified dimensions.
then(InlineSpan span) → Widget: Available on Widget, provided by the TextExtension extension
Appends an inline span to the current text widget.
thenButton({required VoidCallback onPressed, required Widget child}) → Widget: Available on Widget, provided by the TextExtension extension
Appends a button widget to the current text widget.
thenInlineCode(String text) → Widget: Available on Widget, provided by the TextExtension extension
Appends inline code to the current text widget.
thenText(String text) → Widget: Available on Widget, provided by the TextExtension extension
Appends a text span to the current text widget.
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode: Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String: A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) → String: Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String: Returns a one-line detailed description of the object.
inherited
toStringShort() → String: A short, textual description of this widget.
inherited
transform({Key? key, required Matrix4 transform}) → Widget: Available on Widget, provided by the WidgetExtension extension
Applies a transformation matrix to this widget.
withAlign(AlignmentGeometry alignment) → Widget: Available on Widget, provided by the WidgetExtension extension
Aligns this widget within its parent.
withOpacity(double opacity) → Widget: Available on Widget, provided by the WidgetExtension extension
Applies opacity to this widget.
withPadding({double? top, double? bottom, double? left, double? right, double? horizontal, double? vertical, double? all, EdgeInsetsGeometry? padding}) → Widget: Available on Widget, provided by the WidgetExtension extension
Wraps this widget in a Padding widget.

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Static Methods

collapseAll<K>(List<TreeNode<K>> nodes) → List<TreeNode<K>>: Collapses all nodes in the tree.
collapseItem<K>(List<TreeNode<K>> nodes, K target) → List<TreeNode<K>>: Collapses a node by its item value.
collapseNode<K>(List<TreeNode<K>> nodes, TreeNode<K> target) → List<TreeNode<K>>: Collapses a specific node.
defaultItemExpandHandler<K>(List<TreeNode<K>> nodes, TreeNode<K> target, ValueChanged<List<TreeNode<K>>> onChanged) → ValueChanged<bool>: Creates a default expand/collapse handler for tree items.
defaultSelectionHandler<K>(List<TreeNode<K>> nodes, ValueChanged<List<TreeNode<K>>> onChanged) → TreeNodeSelectionChanged<K>: Creates a default selection changed handler for tree nodes.
deselectAll<K>(List<TreeNode<K>> nodes) → List<TreeNode<K>>: Deselects all nodes in the tree.
deselectItem<K>(List<TreeNode<K>> nodes, K target) → List<TreeNode<K>>: Deselects a node by its item value.
deselectItems<K>(List<TreeNode<K>> nodes, Iterable<K> deselectedItems) → List<TreeNode<K>>: Deselects nodes by their item values.
deselectNode<K>(List<TreeNode<K>> nodes, TreeNode<K> target) → List<TreeNode<K>>: Deselects a specific node.
deselectNodes<K>(List<TreeNode<K>> nodes, Iterable<TreeNode<K>> deselectedNodes) → List<TreeNode<K>>: Deselects specific nodes.
expandAll<K>(List<TreeNode<K>> nodes) → List<TreeNode<K>>: Expands all nodes in the tree.
expandItem<K>(List<TreeNode<K>> nodes, K target) → List<TreeNode<K>>: Expands a node by its item value.
expandNode<K>(List<TreeNode<K>> nodes, TreeNode<K> target) → List<TreeNode<K>>: Expands a specific node.
getSelectedItems<K>(List<TreeNode<K>> nodes) → List<K>: Gets all selected item values from the tree.
getSelectedNodes<K>(List<TreeNode<K>> nodes) → List<TreeNode<K>>: Gets all selected nodes from the tree.
replaceItem<K>(List<TreeNode<K>> nodes, K oldItem, TreeNode<K> newItem) → List<TreeNode<K>>: Replaces a node by matching its item value.
replaceNode<K>(List<TreeNode<K>> nodes, TreeNode<K> oldNode, TreeNode<K> newNode) → List<TreeNode<K>>: Replaces a specific node in the tree.
replaceNodes<K>(List<TreeNode<K>> nodes, TreeNodeUnaryOperator<K> operator) → List<TreeNode<K>>: Applies a transformation operator to all nodes in a tree.
replaceNodesWithParent<K>(List<TreeNode<K>> nodes, TreeNodeUnaryOperatorWithParent<K> operator) → List<TreeNode<K>>: Applies a transformation operator to all nodes with parent context.
selectAll<K>(List<TreeNode<K>> nodes) → List<TreeNode<K>>: Selects all nodes in the tree.
selectItem<K>(List<TreeNode<K>> nodes, K target) → List<TreeNode<K>>: Selects a node by its item value.
selectItems<K>(List<TreeNode<K>> nodes, Iterable<K> selectedItems) → List<TreeNode<K>>: Selects nodes by their item values.
selectNode<K>(List<TreeNode<K>> nodes, TreeNode<K> target) → List<TreeNode<K>>: Selects a specific node.
selectNodes<K>(List<TreeNode<K>> nodes, Iterable<TreeNode<K>> selectedNodes) → List<TreeNode<K>>: Selects specific nodes.
setSelectedItems<K>(List<TreeNode<K>> nodes, Iterable<K> selectedItems) → List<TreeNode<K>>: Sets the selected items by value, replacing current selection.
setSelectedNodes<K>(List<TreeNode<K>> nodes, Iterable<TreeNode<K>> selectedNodes) → List<TreeNode<K>>: Sets the selected nodes, replacing current selection.
toggleSelectAll<K>(List<TreeNode<K>> nodes) → List<TreeNode<K>>: Toggles selection state of all nodes.
toggleSelectItem<K>(List<TreeNode<K>> nodes, K target) → List<TreeNode<K>>: Toggles selection state of a node by its item value.
toggleSelectItems<K>(List<TreeNode<K>> nodes, Iterable<K> targets) → List<TreeNode<K>>: Toggles selection state of multiple items.
toggleSelectNode<K>(List<TreeNode<K>> nodes, TreeNode<K> target) → List<TreeNode<K>>: Toggles selection state of a specific node.
toggleSelectNodes<K>(List<TreeNode<K>> nodes, Iterable<TreeNode<K>> targets) → List<TreeNode<K>>: Toggles selection state of multiple nodes.
updateRecursiveSelection<K>(List<TreeNode<K>> nodes) → List<TreeNode<K>>: Updates selection state to maintain parent-child consistency.