Tree

Guidelines
React API Reference
Blazor API Reference

Tree components provide a way to display hierarchical data in an expandable/collapsible structure, allowing users to navigate through complex nested information efficiently while maintaining context of the overall hierarchy.

Guidance

Aspect	Best Practice
Usage	Use for hierarchical data structures like file systems, organizational charts, taxonomies, or nested categories that benefit from progressive disclosure.
Content	Use clear, descriptive labels for each node. Show relevant icons or indicators to help users understand item types and relationships.
Behavior	Support both mouse and keyboard navigation. Provide expand/collapse functionality and clear visual indicators for expandable nodes.
States	Clearly distinguish between expanded, collapsed, selected, and loading states. Show parent-child relationships through visual hierarchy.
Performance	Implement lazy loading for large datasets. Consider virtualization for trees with hundreds or thousands of nodes.
Examples	File explorers, navigation menus, category browsers, organizational structures, or any nested data that users need to explore incrementally.

Best Practices

Progressive Disclosure: Show only top-level items initially, allowing users to explore deeper levels as needed.
Visual Hierarchy: Use indentation, connecting lines, and icons to clearly show parent-child relationships.
Keyboard Navigation: Support arrow keys for navigation, Enter/Space for selection, and appropriate focus management.
Loading States: Show loading indicators for async operations and provide feedback during data fetching.
Selection Clarity: Make selected items clearly visible and maintain selection state appropriately.
Expand/Collapse Indicators: Use consistent icons or symbols to indicate expandable nodes and their current state.

Do’s and Don’ts

Do

Use for hierarchical data that benefits from progressive disclosure.
Provide clear visual indicators for expandable/collapsible nodes.
Support keyboard navigation and accessibility features.
Show parent-child relationships through visual hierarchy.

Don't

Use for flat data that doesn’t have natural hierarchy.
Auto-expand all nodes by default for large trees.
Make the tree too deep without providing context or navigation aids.
Forget to handle loading states for large or dynamic datasets.

Additional Guidance

Psychological Impact:
- Familiar Mental Model: Trees mirror familiar concepts like folder structures and organizational charts.
- Spatial Awareness: Visual hierarchy helps users understand their location within the data structure.
- Controlled Exploration: Progressive disclosure prevents information overload while enabling deep exploration.

Import

import { Tree } from '@strongtie/design-system/tree';

Usage

<Tree>
  <TreeItem value="app" label="app">
    <TreeItem value="page.tsx" label="page.tsx" />
    <TreeItem value="layout.tsx" label="layout.tsx" />
  </TreeItem>
  <TreeItem value="components" label="components">
    <TreeItem value="header.tsx" label="header.tsx" />
    <TreeItem value="footer.tsx" label="footer.tsx" />
  </TreeItem>
</Tree>

`<Tree>` Props

selectable

boolean

default:"true"

Whether tree items can be selected.

multiple

boolean

default:"false"

Whether multiple items can be selected at once.

collapsible

boolean

default:"true"

Whether tree items can be collapsed and expanded.

defaultExpanded

string[]

default:"[]"

Array of item values that should be expanded by default.

defaultSelected

string | string[]

Default selected item value(s).

onSelect

(value: string | string[]) => void

Callback fired when selection changes.

onExpand

(expandedItems: string[]) => void

Callback fired when expanded state changes.

`<TreeItem>` Props

value

string

required

Unique identifier for the tree item.

label

string

required

Display text for the tree item.

icon

ReactNode

Optional icon to display before the label.

disabled

boolean

default:"false"

Whether the tree item is disabled.

Usage Examples

const treeData = [
  {
    id: "1",
    name: "src",
    type: "folder",
    children: [
      { id: "2", name: "components", type: "folder" },
      { id: "3", name: "pages", type: "folder" },
      { id: "4", name: "index.ts", type: "file" }
    ]
  },
  {
    id: "5",
    name: "package.json",
    type: "file"
  }
];

<Tree data={treeData} onSelect={(item) => console.log('Selected:', item)} />

Styling Classes

The following CSS classes are applied by the Tree component:

tree – Root tree container with basic styling and layout
tree-node-container – Container for each tree node with positioning
tree-line-container – Container for visual connection lines between nodes
tree-line – Visual lines connecting parent and child nodes
tree-button – Interactive button element for each tree node
tree-chevron – Expand/collapse indicator icon
tree-chevron-open – Applied when node is expanded
tree-spacer – Spacing element for nodes without children
tree-content – Content container for each node
tree-content-selected – Applied to selected tree nodes
tree-icon – Base class for node icons
tree-folder-icon – Specific styling for folder icons
tree-file-icon – Specific styling for file icons
tree-text – Text content within tree nodes
tree-text-no-icons – Text styling when icons are disabled
tree-collapsible-content – Container for child nodes

For more examples, visit the Storybook.

Example

<StudsTree>
    <StudsTreeItem Text="app">
        <StudsTreeItem Text="page.tsx" />
        <StudsTreeItem Text="layout.tsx" />
    </StudsTreeItem>
    <StudsTreeItem Text="components">
        <StudsTreeItem Text="header.tsx" />
        <StudsTreeItem Text="footer.tsx" />
    </StudsTreeItem>
</StudsTree>

`StudsTree` Parameters

AllowCheckBoxes

bool

default:"false"

Gets or sets whether the tree displays checkboxes for each item.

AllowCheckChildren

bool

default:"true"

Gets or sets whether checking a parent item also checks all its children.

AllowCheckParents

bool

default:"true"

Gets or sets whether checking children affects the parent’s checked state.

SingleExpand

bool

default:"false"

Gets or sets whether only one branch can be expanded at a time.

Value

Object

Gets or sets the selected item’s value.

SelectItemAriaLabel

string

Gets or sets the aria-label for the selected item.

ItemContentCssClass

string

Gets or sets the CSS class for the item content.

ItemIconCssClass

string

Gets or sets the CSS class for the item icon.

ItemLabelCssClass

string

Gets or sets the CSS class for the item label.

ValueChanged

EventCallback<Object>

Callback invoked when the selected value changes.

CheckedValues

IEnumerable<object>

Gets or sets the collection of checked item values.

Data

IEnumerable

Specifies the collection of data items which StudsTree will create its items from.

ItemRender

Action<TreeItemRenderEventArgs>

A callback that will be invoked when item is rendered.

ChildContent

RenderFragment

Gets or sets the child items content.

CheckedValuesChanged

EventCallback<IEnumerable<object>>

Callback invoked when the checked values collection changes.

Change

EventCallback<TreeEventArgs>

Callback invoked when an item is selected.

Expand

EventCallback<TreeExpandEventArgs>

Callback invoked when an item is expanded.

Collapse

EventCallback<TreeEventArgs>

Callback invoked when an item is collapsed.

Callback invoked when right-clicking an item.

Attributes

Dictionary<string, object>

Specifies additional custom attributes that will be rendered by the component.

MouseEnter

EventCallback<ElementReference>

Gets or sets the callback that is invoked when the mouse enters an item.

MouseLeave

EventCallback<ElementReference>

Gets or sets the callback that is invoked when the mouse leaves an item.

A callback that will be invoked when the user right-clicks the component. Commonly used to display a context menu.

Culture

CultureInfo

default:"CultureInfo.CurrentCulture"

Gets or sets the culture used to display localizable data (numbers, dates). Set by default to “CultureInfo.CurrentCulture”.

Style

string

Gets or sets the inline CSS style.

Visible

bool

default:"true"

Gets or sets a value indicating whether this “T:Studs.StudsComponent” is visible. Invisible components are not rendered.

`StudsTreeItem` Parameters

Text

string

Gets or sets the display text of the tree item.

Value

object

Gets or sets the value associated with this item.

Checkable

bool

default:"true"

Gets or sets whether this item can be checked.

HasChildren

bool

default:"false"

Gets or sets whether this item has child items.

Expanded

bool

default:"false"

Gets or sets whether this item is expanded.

Selected

bool

default:"false"

Gets or sets whether this item is selected.

Template

RenderFragment<StudsTreeItem>

Gets or sets custom template for rendering the item content.

ChildContent

RenderFragment

Gets or sets the child items content.

Tree

StudsTree

The StudsTree which this item is part of.

ParentItem

StudsTreeItem

The parent item of this tree item.

Data

IEnumerable

The children data.

ContentCssClass

string

Gets or sets the CSS class for the item content.

IconCssClass

string

Gets or sets the CSS class for the item icon.

LabelCssClass

string

Gets or sets the CSS class for the item label.

`StudsTreeLevel` Parameters

For data-bound scenarios:

TextProperty

string

Specifies the property name to use for item text.

CheckableProperty

Specifies the name of the property which provides values for the Checkable property of the child items.

ChildrenProperty

string

Specifies the property name that contains child items.

HasChildren

Func<object, bool>

default:"value => true"

Function that determines if an item has children.

Expanded

Func<object, bool>

default:"value => false"

Function that determines if an item should be expanded.

Selected

Func<object, bool>

default:"value => false"

Function that determines if an item should be selected.

Text

Func<object, string>

Function that determines the display text for an item.

Checkable

Func<object, bool>

Determines the if the checkbox of the child item can be checked.

Template

RenderFragment<StudsTreeItem>

Gets or sets the template.

Tree

StudsTree

The StudsTree which this item is part of.

Attributes

Dictionary<string, object>

Specifies additional custom attributes that will be rendered by the component.

MouseEnter

EventCallback<ElementReference>

Gets or sets the callback that is invoked when the mouse enters an item.

MouseLeave

EventCallback<ElementReference>

Gets or sets the callback that is invoked when the mouse leaves an item.

A callback that will be invoked when the user right-clicks the component. Commonly used to display a context menu.

Culture

CultureInfo

default:"CultureInfo.CurrentCulture"

Gets or sets the culture used to display localizable data (numbers, dates). Set by default to “CultureInfo.CurrentCulture”.

Style

string

Gets or sets the inline CSS style.

Visible

bool

default:"true"

Gets or sets a value indicating whether this “T:Studs.StudsComponent” is visible. Invisible components are not rendered.

Usage Examples

<StudsTree>
    <StudsTreeItem Text="Documents">
        <StudsTreeItem Text="report.pdf" />
        <StudsTreeItem Text="presentation.pptx" />
    </StudsTreeItem>
    <StudsTreeItem Text="Images">
        <StudsTreeItem Text="photo1.jpg" />
        <StudsTreeItem Text="photo2.png" />
    </StudsTreeItem>
</StudsTree>

Styling Classes

The following CSS classes are applied by the Tree components:

tree – Root tree container with basic layout and styling
tree-container – List container for tree items with proper ARIA structure
tree-item – Individual tree item wrapper with hierarchy indicators
tree-item-content – Content area for each tree item
tree-item-icon – Icon display area for tree items
tree-item-label – Text label area for tree items
tree-item-expand – Expand/collapse button for parent nodes
tree-item-selected – Applied to selected tree items
tree-item-expanded – Applied to expanded parent items
tree-checkbox – Checkbox styling when AllowCheckBoxes is enabled
tree-level-{n} – Applied based on nesting depth for visual hierarchy
Custom classes can be applied via ItemContentCssClass, ItemIconCssClass, and ItemLabelCssClass parameters

For more examples, visit the Storybook.

Getting Started

Foundations

Components

Integration Guides

Content

Guidance

Best Practices

Do’s and Don’ts

Do

Don't

Additional Guidance

`<Tree>` Props

`<TreeItem>` Props

Usage Examples

Styling Classes

`StudsTree` Parameters

`StudsTreeItem` Parameters

`StudsTreeLevel` Parameters

Usage Examples

Styling Classes

Getting Started

Foundations

Components

Integration Guides

Content

​Guidance

​Best Practices

​Do’s and Don’ts

Do

Don't

​Additional Guidance

​<Tree> Props

​<TreeItem> Props

​Usage Examples

​Styling Classes

​StudsTree Parameters

​StudsTreeItem Parameters

​StudsTreeLevel Parameters

​Usage Examples

​Styling Classes

Guidance

Best Practices

Do’s and Don’ts

Additional Guidance

`<Tree>` Props

`<TreeItem>` Props

Usage Examples

Styling Classes

`StudsTree` Parameters

`StudsTreeItem` Parameters

`StudsTreeLevel` Parameters

Usage Examples

Styling Classes