TreeView.md

March 25, 2026 · View on GitHub

The TreeView component is meant to emulate the asp:TreeView control in markup and is defined in the System.Web.UI.WebControls.TreeView class

Features supported in Blazor

Static Tree Nodes
Checkbox display
TreeNode expand and collapse events
TreeNode checkbox checked / unchecked events
XmlDocument databinding
SiteMap databinding as an XmlDocument
Databinding events
Accessibility features (see below)
Node-Level Styles - NodeStyle, HoverNodeStyle, LeafNodeStyle, ParentNodeStyle, RootNodeStyle, SelectedNodeStyle
Selection - SelectedNode, SelectedValue, SelectedNodeChanged event
Expand/Collapse - ExpandAll(), CollapseAll(), ExpandDepth, NodeIndent, PathSeparator, FindNode()
Image Customization - CollapseImageUrl, ExpandImageUrl, NoExpandImageUrl, CollapseImageToolTip, ExpandImageToolTip, LineImagesFolder
Data Binding Configuration - AutoGenerateDataBindings, MaxDataBindDepth, EnableClientScript

The TreeView component includes an optional UseAccessibilityFeatures parameter that enhances the component for users with disabilities, particularly for keyboard navigation and screen reader support.

Enabling Accessibility Features

To enable accessibility features, set the UseAccessibilityFeatures parameter to true:

<TreeView UseAccessibilityFeatures="true">
    <Nodes>
        <TreeNode Text="Root Node" Expanded="true">
            <TreeNode Text="Child Node" />
        </TreeNode>
    </Nodes>
</TreeView>

When Accessibility Features are Enabled

The TreeView component provides the following enhancements:

ARIA Attributes

role="tree": Applied to the TreeView container to identify it as a tree widget
aria-label="Tree navigation": Provides a descriptive label for screen readers
role="treeitem": Applied to each TreeNode to identify it as a tree item
aria-level: Indicates the depth level of each node (1 for root nodes, 2 for children, etc.)
aria-expanded: For nodes with children, indicates whether the node is expanded ("true") or collapsed ("false")
aria-label: Added to expand/collapse links to provide descriptive text for screen readers

With accessibility features enabled, users can navigate the TreeView using keyboard shortcuts:

Arrow Right (→): Expands a collapsed node that has children
Arrow Left (←): Collapses an expanded node that has children
Enter or Space: Activates the node's link or expands/collapses the node
Tab: Moves focus into and out of the TreeView

Focus Management

Each TreeNode receives a tabindex="0" attribute, making it keyboard accessible
Nodes can receive focus and respond to keyboard events
Visual focus indicators follow browser defaults

Benefits for Different Users

The accessibility features address several user needs:

Keyboard Users: Can navigate and interact with the TreeView without a mouse
Screen Reader Users: Get proper semantic information about the tree structure and node states
Speech Recognition Users: Benefit from larger interactive areas due to keyboard focus support
Touch Device Users: While the core issue of small touch targets isn't fully addressed, keyboard equivalents provide an alternative interaction method

Backwards Compatibility

By default, UseAccessibilityFeatures is false, ensuring existing implementations continue to work without changes. The HTML output remains identical to the original Web Forms TreeView when accessibility features are disabled.

Usage Notes

ShowCheckBoxes attribute, when specifying multiple values, should be separated by a vertical pipe | instead of commas
For the best user experience with assistive technologies, set UseAccessibilityFeatures="true"

Syntax Comparison

=== "Web Forms"

```html
<asp:TreeView
    AccessKey="string"
    AutoGenerateDataBindings="True|False"
    BackColor="color name|#dddddd"
    BorderColor="color name|#dddddd"
    BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|Groove|Ridge|
        Inset|Outset"
    BorderWidth="size"
    CollapseImageToolTip="string"
    CollapseImageUrl="uri"
    CssClass="string"
    DataSource="string"
    DataSourceID="string"
    EnableClientScript="True|False"
    Enabled="True|False"
    EnableTheming="True|False"
    EnableViewState="True|False"
    ExpandDepth="string|FullyExpand|0|1|2|3|4|5|6|7|8|9|10|11|12|13|
        14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30"
    ExpandImageToolTip="string"
    ExpandImageUrl="uri"
    Font-Bold="True|False"
    Font-Italic="True|False"
    Font-Names="string"
    Font-Overline="True|False"
    Font-Size="string|Smaller|Larger|XX-Small|X-Small|Small|Medium|
       Large|X-Large|XX-Large"
    Font-Strikeout="True|False"
    Font-Underline="True|False"
    ForeColor="color name|#dddddd"
    Height="size"
    ID="string"
    ImageSet="Custom|XPFileExplorer|Msdn|WindowsHelp|Simple|Simple2|
        BulletedList|BulletedList2|BulletedList3|BulletedList4|
        Arrows|News|Contacts|Inbox|Events|Faq"
    LineImagesFolder="string"
    MaxDataBindDepth="integer"
    NodeIndent="integer"
    NodeWrap="True|False"
    NoExpandImageUrl="uri"
    OnDataBinding="DataBinding event handler"
    OnDataBound="DataBound event handler"
    OnDisposed="Disposed event handler"
    OnInit="Init event handler"
    OnLoad="Load event handler"
    OnPreRender="PreRender event handler"
    OnSelectedNodeChanged="SelectedNodeChanged event handler"
    OnTreeNodeCheckChanged="TreeNodeCheckChanged event handler"
    OnTreeNodeCollapsed="TreeNodeCollapsed event handler"
    OnTreeNodeDataBound="TreeNodeDataBound event handler"
    OnTreeNodeExpanded="TreeNodeExpanded event handler"
    OnTreeNodePopulate="TreeNodePopulate event handler"
    OnUnload="Unload event handler"
    PathSeparator="string"
    PopulateNodesFromClient="True|False"
    runat="server"
    ShowCheckBoxes="None|Root|Parent|Leaf|All"
    ShowExpandCollapse="True|False"
    ShowLines="True|False"
    SkinID="string"
    SkipLinkText="string"
    Style="string"
    TabIndex="integer"
    Target="string"
    ToolTip="string"
    Visible="True|False"
    Width="size"
>
        <DataBindings>
                <asp:TreeNodeBinding
                    DataMember="string"
                    Depth="integer"
                    FormatString="string"
                    ImageToolTip="string"
                    ImageToolTipField="string"
                    ImageUrl="uri"
                    ImageUrlField="string"
                    NavigateUrl="uri"
                    NavigateUrlField="string"
                    PopulateOnDemand="True|False"
                    SelectAction="Select|Expand|SelectExpand|None"
                    ShowCheckBox="string"
                    Target="string"
                    TargetField="string"
                    Text="string"
                    TextField="string"
                    ToolTip="string"
                    ToolTipField="string"
                    Value="string"
                    ValueField="string"
                />
        </DataBindings>
        <HoverNodeStyle />
        <LeafNodeStyle
            BackColor="color name|#dddddd"
            BorderColor="color name|#dddddd"
            BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|
                Groove|Ridge|Inset|Outset"
            BorderWidth="size"
            ChildNodesPadding="size"
            CssClass="string"
            Font-Bold="True|False"
            Font-Italic="True|False"
            Font-Names="string"
            Font-Overline="True|False"
            Font-Size="string|Smaller|Larger|XX-Small|X-Small|Small|
                Medium|Large|X-Large|XX-Large"
            Font-Strikeout="True|False"
            Font-Underline="True|False"
            ForeColor="color name|#dddddd"
            Height="size"
            HorizontalPadding="size"
            ImageUrl="uri"
            NodeSpacing="size"
            OnDisposed="Disposed event handler"
            VerticalPadding="size"
            Width="size"
        />
        <LevelStyles>
                <asp:TreeNodeStyle
                    BackColor="color name|#dddddd"
                    BorderColor="color name|#dddddd"
                    BorderStyle="NotSet|None|Dotted|Dashed|Solid|
                        Double|Groove|Ridge|Inset|Outset"
                    BorderWidth="size"
                    ChildNodesPadding="size"
                    CssClass="string"
                    Font-Bold="True|False"
                    Font-Italic="True|False"
                    Font-Names="string"
                    Font-Overline="True|False"
                    Font-Size="string|Smaller|Larger|XX-Small|
                        X-Small|Small|Medium|Large|X-Large|XX-Large"
                    Font-Strikeout="True|False"
                    Font-Underline="True|False"
                    ForeColor="color name|#dddddd"
                    Height="size"
                    HorizontalPadding="size"
                    ImageUrl="uri"
                    NodeSpacing="size"
                    OnDisposed="Disposed event handler"
                    VerticalPadding="size"
                    Width="size"
                />
        </LevelStyles>
        <Nodes>
                <asp:TreeNode
                    Checked="True|False"
                    Expanded="string"
                    ImageToolTip="string"
                    ImageUrl="uri"
                    NavigateUrl="uri"
                    PopulateOnDemand="True|False"
                    SelectAction="Select|Expand|SelectExpand|None"
                    Selected="True|False"
                    ShowCheckBox="string"
                    Target="string"
                    Text="string"
                    ToolTip="string"
                    Value="string"
>
                </asp:TreeNode>
        </Nodes>
        <NodeStyle
            BackColor="color name|#dddddd"
            BorderColor="color name|#dddddd"
            BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|
                Groove|Ridge|Inset|Outset"
            BorderWidth="size"
            ChildNodesPadding="size"
            CssClass="string"
            Font-Bold="True|False"
            Font-Italic="True|False"
            Font-Names="string"
            Font-Overline="True|False"
            Font-Size="string|Smaller|Larger|XX-Small|X-Small|Small|
                Medium|Large|X-Large|XX-Large"
            Font-Strikeout="True|False"
            Font-Underline="True|False"
            ForeColor="color name|#dddddd"
            Height="size"
            HorizontalPadding="size"
            ImageUrl="uri"
            NodeSpacing="size"
            OnDisposed="Disposed event handler"
            VerticalPadding="size"
            Width="size"
        />
        <ParentNodeStyle
            BackColor="color name|#dddddd"
            BorderColor="color name|#dddddd"
            BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|
                Groove|Ridge|Inset|Outset"
            BorderWidth="size"
            ChildNodesPadding="size"
            CssClass="string"
            Font-Bold="True|False"
            Font-Italic="True|False"
            Font-Names="string"
            Font-Overline="True|False"
            Font-Size="string|Smaller|Larger|XX-Small|X-Small|Small|
                Medium|Large|X-Large|XX-Large"
            Font-Strikeout="True|False"
            Font-Underline="True|False"
            ForeColor="color name|#dddddd"
            Height="size"
            HorizontalPadding="size"
            ImageUrl="uri"
            NodeSpacing="size"
            OnDisposed="Disposed event handler"
            VerticalPadding="size"
            Width="size"
        />
        <RootNodeStyle
            BackColor="color name|#dddddd"
            BorderColor="color name|#dddddd"
            BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|
                Groove|Ridge|Inset|Outset"
            BorderWidth="size"
            ChildNodesPadding="size"
            CssClass="string"
            Font-Bold="True|False"
            Font-Italic="True|False"
            Font-Names="string"
            Font-Overline="True|False"
            Font-Size="string|Smaller|Larger|XX-Small|X-Small|Small|
                Medium|Large|X-Large|XX-Large"
            Font-Strikeout="True|False"
            Font-Underline="True|False"
            ForeColor="color name|#dddddd"
            Height="size"
            HorizontalPadding="size"
            ImageUrl="uri"
            NodeSpacing="size"
            OnDisposed="Disposed event handler"
            VerticalPadding="size"
            Width="size"
        />
        <SelectedNodeStyle
            BackColor="color name|#dddddd"
            BorderColor="color name|#dddddd"
            BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|
                Groove|Ridge|Inset|Outset"
            BorderWidth="size"
            ChildNodesPadding="size"
            CssClass="string"
            Font-Bold="True|False"
            Font-Italic="True|False"
            Font-Names="string"
            Font-Overline="True|False"
            Font-Size="string|Smaller|Larger|XX-Small|X-Small|Small|
                Medium|Large|X-Large|XX-Large"
            Font-Strikeout="True|False"
            Font-Underline="True|False"
            ForeColor="color name|#dddddd"
            Height="size"
            HorizontalPadding="size"
            ImageUrl="uri"
            NodeSpacing="size"
            OnDisposed="Disposed event handler"
            VerticalPadding="size"
            Width="size"
        />
</asp:TreeView>
```

=== "Blazor"

```html
<TreeView
    AutoGenerateDataBindings=bool
    CollapseImageToolTip=string
    CollapseImageUrl=string
    CssClass=string
    DataSource=XmlDocument
    EnableClientScript=bool
    ExpandDepth=int
    ExpandImageToolTip=string
    ExpandImageUrl=string
    ID=string
    LineImagesFolder=string
    MaxDataBindDepth=int
    NodeIndent=int
    NoExpandImageUrl=string
    PathSeparator=char
    SelectedNodeChanged=EventCallback<TreeNodeEventArgs>
    ShowCheckBoxes="None|Root|Parent|Leaf|All"
    ShowExpandCollapse=bool
    ShowLines=bool
    Target=string
    UseAccessibilityFeatures=bool
    Visible=bool
>
    <HoverNodeStyle CssClass="string" ... />
    <LeafNodeStyle CssClass="string" ... />
    <NodeStyle CssClass="string" ... />
    <Nodes>
        <TreeNode
            Checked=bool
            Expanded=bool
            ImageUrl=string
            NavigateUrl=string
            Selected=bool
            ShowCheckBox=bool
            Target=string
            Text=string
            ToolTip=string
            Value=string
        >
            <TreeNode Text="Child" Value="child" />
        </TreeNode>
    </Nodes>
    <ParentNodeStyle CssClass="string" ... />
    <RootNodeStyle CssClass="string" ... />
    <SelectedNodeStyle CssClass="string" ... />
</TreeView>
```

Examples

Basic TreeView with Nodes

<TreeView ShowExpandCollapse="true">
    <Nodes>
        <TreeNode Text="Products" Value="products" Expanded="true">
            <TreeNode Text="Electronics" Value="electronics">
                <TreeNode Text="Laptops" Value="laptops" />
                <TreeNode Text="Phones" Value="phones" />
            </TreeNode>
            <TreeNode Text="Clothing" Value="clothing">
                <TreeNode Text="Shirts" Value="shirts" />
                <TreeNode Text="Pants" Value="pants" />
            </TreeNode>
        </TreeNode>
    </Nodes>
</TreeView>

Node Selection

<TreeView SelectedNodeChanged="HandleNodeSelected">
    <Nodes>
        <TreeNode Text="Home" Value="home" />
        <TreeNode Text="About" Value="about" />
        <TreeNode Text="Contact" Value="contact" />
    </Nodes>
    <SelectedNodeStyle CssClass="selected" BackColor="LightBlue" />
</TreeView>

<p>Selected: @selectedValue</p>

@code {
    private string selectedValue = "";

    private void HandleNodeSelected(TreeNodeEventArgs e)
    {
        selectedValue = e.Node.Value;
    }
}

Node-Level Styles

@* Apply different styles to root, parent, and leaf nodes *@
<TreeView ShowExpandCollapse="true">
    <Nodes>
        <TreeNode Text="Documents" Value="docs" Expanded="true">
            <TreeNode Text="Reports" Value="reports">
                <TreeNode Text="Q1 Report" Value="q1" />
                <TreeNode Text="Q2 Report" Value="q2" />
            </TreeNode>
        </TreeNode>
    </Nodes>
    <RootNodeStyle CssClass="root-node" ForeColor="DarkBlue" Font-Bold="true" />
    <ParentNodeStyle CssClass="parent-node" ForeColor="Navy" />
    <LeafNodeStyle CssClass="leaf-node" ForeColor="Black" />
    <HoverNodeStyle CssClass="hover-node" BackColor="LightYellow" />
    <SelectedNodeStyle CssClass="selected-node" BackColor="LightBlue" />
</TreeView>

!!! note "Style Priority" When multiple styles apply to a node, the priority order is: SelectedNodeStyle > type-specific style (Root/Parent/Leaf) > NodeStyle (fallback).

Expand/Collapse Control

@* ExpandDepth controls initial expansion. -1 = fully expanded. *@
<TreeView @ref="treeRef"
          ExpandDepth="1"
          NodeIndent="25"
          PathSeparator="/">
    <Nodes>
        <TreeNode Text="Root" Value="root">
            <TreeNode Text="Level 1" Value="level1">
                <TreeNode Text="Level 2" Value="level2" />
            </TreeNode>
        </TreeNode>
    </Nodes>
</TreeView>

<Button Text="Expand All" OnClick="ExpandAll" />
<Button Text="Collapse All" OnClick="CollapseAll" />
<Button Text="Find Node" OnClick="FindSpecific" />

@code {
    private TreeView treeRef;

    private void ExpandAll() => treeRef.ExpandAll();
    private void CollapseAll() => treeRef.CollapseAll();
    private void FindSpecific()
    {
        // Find node by path: "root/level1/level2"
        var node = treeRef.FindNode("root/level1/level2");
    }
}

Data Binding with XmlDocument

@using System.Xml

<TreeView DataSource="@sitemapXml"
          ShowExpandCollapse="true">
    <DataBindings>
        <TreeNodeBinding DataMember="siteMapNode"
                         TextField="title"
                         NavigateUrlField="url" />
    </DataBindings>
</TreeView>

@code {
    private XmlDocument sitemapXml;

    protected override void OnInitialized()
    {
        sitemapXml = new XmlDocument();
        sitemapXml.LoadXml(@"
            <siteMap>
                <siteMapNode title='Home' url='/'>
                    <siteMapNode title='Products' url='/products' />
                    <siteMapNode title='About' url='/about' />
                </siteMapNode>
            </siteMap>");
    }
}

Selection Properties Reference

Property/Event	Type	Default	Description
`SelectedNode`	`TreeNode`	`null`	Read-only. The currently selected node.
`SelectedValue`	`string`	`null`	Read-only. The `Value` of the selected node.
`SelectedNodeChanged`	`EventCallback<TreeNodeEventArgs>`	—	Fires when the selected node changes.

Node Style Sub-Components Reference

All node style sub-components use TreeNodeStyle which supports:

Property	Type	Description
`CssClass`	`string`	CSS class name
`BackColor`	`WebColor`	Background color
`ForeColor`	`WebColor`	Text color
`Font`	`FontInfo`	Font settings
`ImageUrl`	`string`	Custom node icon URL
`HorizontalPadding`	`Unit`	Horizontal padding
`VerticalPadding`	`Unit`	Vertical padding
`ChildNodesPadding`	`Unit`	Padding around child nodes
`NodeSpacing`	`Unit`	Spacing between nodes

Available style sub-components:

Component	Applied To
`<NodeStyle>`	All nodes (fallback)
`<HoverNodeStyle>`	Nodes on mouse hover
`<RootNodeStyle>`	Top-level nodes (no parent)
`<ParentNodeStyle>`	Nodes that have children
`<LeafNodeStyle>`	Nodes with no children
`<SelectedNodeStyle>`	The currently selected node

Expand/Collapse Reference

Property/Method	Type	Default	Description
`ExpandDepth`	`int`	`-1`	Initial expansion depth. `-1` = fully expanded, `0` = all collapsed.
`NodeIndent`	`int`	`20`	Pixel indent per nesting level.
`PathSeparator`	`char`	`'/'`	Separator character for `FindNode()` value paths.
`ExpandAll()`	`void`	—	Expands all nodes recursively.
`CollapseAll()`	`void`	—	Collapses all nodes recursively.
`FindNode(string)`	`TreeNode`	—	Finds a node by its `PathSeparator`-delimited value path (e.g., `"root/child/leaf"`).

Image Customization Reference

Property	Type	Default	Description
`CollapseImageUrl`	`string`	`null`	URL of the image displayed on collapsible (expanded) nodes.
`CollapseImageToolTip`	`string`	`null`	Tooltip text for the collapse image.
`ExpandImageUrl`	`string`	`null`	URL of the image displayed on expandable (collapsed) nodes.
`ExpandImageToolTip`	`string`	`null`	Tooltip text for the expand image.
`NoExpandImageUrl`	`string`	`null`	URL of the image displayed on leaf nodes (no children).
`LineImagesFolder`	`string`	`null`	Path to the folder containing line images for tree structure.

Data Binding Configuration Reference

Property	Type	Default	Description
`AutoGenerateDataBindings`	`bool`	`false`	Whether to automatically create data bindings from a data source.
`MaxDataBindDepth`	`int`	`-1`	Maximum hierarchy depth for data binding. `-1` binds all levels.
`EnableClientScript`	`bool`	`true`	Migration stub — accepted for Web Forms compatibility. Blazor does not use client scripts.