Skip to content

Latest commit

 

History

History
578 lines (518 loc) · 20.2 KB

TreeView.md

File metadata and controls

578 lines (518 loc) · 20.2 KB

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()

Accessibility Features

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

Keyboard Navigation

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:

  1. Keyboard Users: Can navigate and interact with the TreeView without a mouse
  2. Screen Reader Users: Get proper semantic information about the tree structure and node states
  3. Speech Recognition Users: Benefit from larger interactive areas due to keyboard focus support
  4. 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"

Web Forms Declarative Syntax

<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 Syntax

<TreeView
    CssClass=string
    DataSource=XmlDocument
    ExpandDepth=int
    ID=string
    NodeIndent=int
    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").

See Also