TreeView

The TreeView control displays information in a hierarchical structure by using collapsible nodes. This article introduces the TreeView and TreeViewItem controls, and provides examples of their use.

The following illustration is an example of a TreeView control that has nested TreeViewItem controls:

What is a TreeView?

TreeView is an ItemsControl that nests the items by using TreeViewItem controls. The following example creates a TreeView.

<TreeView Name="myTreeViewEvent" >
  <TreeViewItem Header="Employee1" IsSelected="True">
    <TreeViewItem Header="Jesper Aaberg"/>
    <TreeViewItem Header="Employee Number">
      <TreeViewItem Header="12345"/>
    </TreeViewItem>
    <TreeViewItem Header="Work Days">
      <TreeViewItem Header="Monday"/>
      <TreeViewItem Header="Tuesday"/>
      <TreeViewItem Header="Thursday"/>
    </TreeViewItem>
  </TreeViewItem>
  <TreeViewItem Header="Employee2">
    <TreeViewItem Header="Dominik Paiha"/>
    <TreeViewItem Header="Employee Number">
      <TreeViewItem Header="98765"/>
    </TreeViewItem>
    <TreeViewItem Header="Work Days">
      <TreeViewItem Header="Tuesday"/>
      <TreeViewItem Header="Wednesday"/>
      <TreeViewItem Header="Friday"/>
    </TreeViewItem>
  </TreeViewItem>
</TreeView>

Create a TreeView

The TreeView control contains a hierarchy of TreeViewItem controls. A TreeViewItem control is a HeaderedItemsControl that has a Header and an Items collection.

If you're defining a TreeView by using Extensible Application Markup Language (XAML), you can explicitly define the Header content of a TreeViewItem control and the items that make up its collection. The previous illustration demonstrates this method.

You can also specify an ItemsSource as a data source and then specify a HeaderTemplate and ItemTemplate to define the TreeViewItem content.

To define the layout of a TreeViewItem control, you can also use HierarchicalDataTemplate objects. For more information and an example, see Use SelectedValue, SelectedValuePath, and SelectedItem.

If an item isn't a TreeViewItem control, it's automatically enclosed by a TreeViewItem control when the TreeView control is displayed.

Expand and collapse a TreeViewItem

If the user expands a TreeViewItem, the IsExpanded property is set to true. You can also expand or collapse a TreeViewItem without any direct user action by setting the IsExpanded property to true (expand) or false (collapse). When this property changes, an Expanded or Collapsed event occurs.

When the BringIntoView method is called on a TreeViewItem control, the TreeViewItem and its parent TreeViewItem controls expand. If a TreeViewItem isn't visible or partially visible, the TreeView scrolls to make it visible.

Select a TreeViewItem

When a user clicks a TreeViewItem control to select it, the Selected event occurs, and its IsSelected property is set to true. The TreeViewItem also becomes the SelectedItem of the TreeView control. Conversely, when the selection changes from a TreeViewItem control, its Unselected event occurs and its IsSelected property is set to false.

The SelectedItem property on the TreeView control is a read-only property, so you can't explicitly set it. The SelectedItem property is set if the user clicks on a TreeViewItem control or when the IsSelected property is set to true on the TreeViewItem control.

Use the SelectedValuePath property to specify a SelectedValue of a SelectedItem. For more information, see Use SelectedValue, SelectedValuePath, and SelectedItem.

You can register an event handler on the SelectedItemChanged event to determine when a selected TreeViewItem changes. The RoutedPropertyChangedEventArgs<T> that's provided to the event handler specifies the OldValue, which is the previous selection, and the NewValue, which is the current selection. Either value can be null if the application or user hasn't made a previous or current selection.

Style a TreeView

The default style for a TreeView control places it inside a StackPanel object that contains a ScrollViewer control. When you set the Width and Height properties for a TreeView, these values are used to size the StackPanel object that displays the TreeView. If the content to display is larger than the display area, a ScrollViewer automatically displays so that the user can scroll through the TreeView content.

To customize the appearance of a TreeViewItem control, set the Style property to a custom Style.

The following example shows how to set the Foreground and FontSize property values for a TreeViewItem control by using a Style.

<Style TargetType="{x:Type TreeViewItem}">
  <Setter Property="Foreground" Value="Blue"/>
  <Setter Property="FontSize" Value="12"/>
</Style>

Add images and other content to TreeView items

You can include more than one object in the Header content of a TreeViewItem. To include multiple objects in Header content, enclose the objects inside a layout control, such as a Panel or StackPanel.

The following example shows how to define the Header of a TreeViewItem as a CheckBox and TextBlock that are both enclosed in a DockPanel control.

<TreeViewItem>
  <TreeViewItem.Header>
    <DockPanel>
      <CheckBox/>
      <TextBlock>
        TreeViewItem Text
      </TextBlock>
    </DockPanel>
  </TreeViewItem.Header>
</TreeViewItem>

The following example shows how to define a DataTemplate that contains an Image and a TextBlock that are enclosed in a DockPanel control. You can use a DataTemplate to set the HeaderTemplate or ItemTemplate for a TreeViewItem.

<DataTemplate x:Key="NewspaperTVItem">
  <DockPanel>
    <Image Source="images\icon.jpg"/>
    <TextBlock VerticalAlignment="center" Text ="{Binding Path=Name}"/>
  </DockPanel>
</DataTemplate>

Common tasks

The following table lists common tasks for working with the TreeView control:

Related sections

Data Binding Overview

Data Templating Overview

Reference

TreeView TreeViewItem

Styles and templates

You can modify the default ControlTemplate to give the TreeView control a unique appearance. For more information, see What are styles and templates? and How to create a template for a control.

Parts

The TreeView control does not have any named parts.

When you create a ControlTemplate for an TreeView, your template might contain a ItemsPresenter within a ScrollViewer. (The ItemsPresenter displays each item in the TreeView; the ScrollViewer enables scrolling within the control). If the ItemsPresenter is not the direct child of the ScrollViewer, you must give the ItemsPresenter the name, ItemsPresenter.

Visual states

The following table lists the visual states for the TreeView control.

TreeViewItem Parts

The following table lists the named parts for the TreeViewItem control.

TreeViewItem States

The following table lists the visual states for TreeViewItem control.

Related Sections

Data Binding Overview Data Templating Overview