NavigationView Class

Definition

Namespace:

Microsoft.UI.Xaml.Controls

Represents a container that enables navigation of app content. It has a header, a view for the main content, and a menu pane for navigation commands.

This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).

/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
/// [Microsoft.UI.Xaml.CustomAttributes.MUXPropertyChangedCallback(enable=true)]
/// [Microsoft.UI.Xaml.CustomAttributes.MUXPropertyChangedCallbackMethodName(value="OnPropertyChanged")]
/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.UI.Xaml.XamlContract, 65536)]
class NavigationView : ContentControl

[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
[Microsoft.UI.Xaml.CustomAttributes.MUXPropertyChangedCallback(enable=true)]
[Microsoft.UI.Xaml.CustomAttributes.MUXPropertyChangedCallbackMethodName(value="OnPropertyChanged")]
[Windows.Foundation.Metadata.ContractVersion(typeof(Microsoft.UI.Xaml.XamlContract), 65536)]
public class NavigationView : ContentControl

Public Class NavigationView
Inherits ContentControl

<NavigationView .../>

Inheritance

ContentControl

NavigationView

Attributes

MarshalingBehaviorAttribute ThreadingAttribute Microsoft.UI.Xaml.CustomAttributes.MUXPropertyChangedCallbackAttribute Microsoft.UI.Xaml.CustomAttributes.MUXPropertyChangedCallbackMethodNameAttribute ContractVersionAttribute

Examples

Tip

For more info, design guidance, and code examples, see Navigation view.

Open the WinUI 2 Gallery app and see the NavigationView in action.

The WinUI 2 Gallery app includes interactive examples of most WinUI 2 controls, features, and functionality. Get the app from the Microsoft Store or get the source code on GitHub.

Remarks

Access keys for built-in elements

To add access keys for the back arrow and settings buttons that are built-in to NavigationView, you have to use VisualTreeHelper to get a reference to those controls, then set the properties in your code.

This example shows how to handle the Loaded event to find the elements in the visual tree and set the AccessKey and KeyTipPlacementMode properties.

private void NavigationView_Loaded(object sender, RoutedEventArgs e)
{
    // using muxc = Microsoft.UI.Xaml.Controls;

    var navView = sender as muxc.NavigationView;
    var rootGrid = VisualTreeHelper.GetChild(navView, 0) as Grid;

    // Find the back button.
    var paneToggleButtonGrid = VisualTreeHelper.GetChild(rootGrid, 0) as Grid;
    var buttonHolderGrid = VisualTreeHelper.GetChild(paneToggleButtonGrid, 1) as Grid;
    var navigationViewBackButton = VisualTreeHelper.GetChild(buttonHolderGrid, 0) as Button;

    navigationViewBackButton.AccessKey = "A";

    if (navView.PaneDisplayMode == muxc.NavigationViewPaneDisplayMode.Top)
    {
        // Set back button key tip placement mode.
        navigationViewBackButton.KeyTipPlacementMode = Windows.UI.Xaml.Input.KeyTipPlacementMode.Bottom;

        // Find the settings item and set properties.
        var grid = VisualTreeHelper.GetChild(rootGrid, 1) as Grid;
        var topNavArea = VisualTreeHelper.GetChild(grid, 0) as StackPanel;
        var topNavGrid = VisualTreeHelper.GetChild(topNavArea, 1) as Grid;
        var settingsTopNavPaneItem = VisualTreeHelper.GetChild(topNavGrid, 8) as muxc.NavigationViewItem;

        settingsTopNavPaneItem.AccessKey = "S";
        settingsTopNavPaneItem.KeyTipPlacementMode = Windows.UI.Xaml.Input.KeyTipPlacementMode.Bottom;
    }
    else
    {
        // Set back button key tip placement mode.
        navigationViewBackButton.KeyTipPlacementMode = Windows.UI.Xaml.Input.KeyTipPlacementMode.Right;

        // Find the settings item and set properties.
        var grid = VisualTreeHelper.GetChild(rootGrid, 1) as Grid;
        var rootSplitView = VisualTreeHelper.GetChild(grid, 1) as SplitView;
        var grid2 = VisualTreeHelper.GetChild(rootSplitView, 0) as Grid;
        var paneRoot = VisualTreeHelper.GetChild(grid2, 0) as Grid;
        var border = VisualTreeHelper.GetChild(paneRoot, 0) as Border;
        var paneContentGrid = VisualTreeHelper.GetChild(border, 0) as Grid;
        var settingsNavPaneItem = VisualTreeHelper.GetChild(paneContentGrid, 6) as muxc.NavigationViewItem;

        settingsNavPaneItem.AccessKey = "S";
        settingsNavPaneItem.KeyTipPlacementMode = Windows.UI.Xaml.Input.KeyTipPlacementMode.Right;
    }
}

Specific keyboarding guidelines

NavigationView supports hierarchy and nested items, which slightly changes the expected keyboarding behavior. For more information on keyboarding within a hierarchical NavigationView, see the hierarchical NavigationView guidelines documentation.

Control style and template

You can modify the default Style and ControlTemplate to give the control a unique appearance. For information about modifying a control's style and template, see XAML styles. The default style, template, and resources that define the look of the control are included in the generic.xaml file. For design purposes, generic.xaml is installed with the WinUI (Microsoft.UI.Xaml) NuGet package. By default, this location is \Users\<username>\.nuget\packages\microsoft.ui.xaml\<version>\lib\uap10.0\Microsoft.UI.Xaml\Themes\generic.xaml. Styles and resources from different versions of WinUI might have different values.

XAML also includes resources that you can use to modify the colors of a control in different visual states without modifying the control template (modifying these resources is preferred to setting properties). For more info, see the Light-weight styling section of the XAML styles article.

Constructors

NavigationView()

Initializes a new instance of the NavigationView class. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).

Properties

AlwaysShowHeader	Gets or sets a value that indicates whether the header is always visible. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
AlwaysShowHeaderProperty	Identifies the AlwaysShowHeader dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
AutoSuggestBox	Gets or sets an AutoSuggestBox to be displayed in the NavigationView. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
AutoSuggestBoxProperty	Identifies the AutoSuggestBox dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
CompactModeThresholdWidth	Gets or sets the minimum window width at which the NavigationView enters Compact display mode. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
CompactModeThresholdWidthProperty	Identifies the CompactModeThresholdWidth dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
CompactPaneLength	Gets or sets the width of the NavigationView pane in its compact display mode. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
CompactPaneLengthProperty	Identifies the CompactPaneLength dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
ContentOverlay	Gets or sets a UI element that is shown at the top of the control, below the pane if PaneDisplayMode is Top. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
ContentOverlayProperty	Identifies the ContentOverlay dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
DisplayMode	Gets a value that specifies how the pane and content areas of a NavigationView are being shown. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
DisplayModeProperty	Identifies the DisplayMode dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
ExpandedModeThresholdWidth	Gets or sets the minimum window width at which the NavigationView enters Expanded display mode. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
ExpandedModeThresholdWidthProperty	Identifies the ExpandedModeThresholdWidth dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
FooterMenuItems	Gets the list of objects to be used as navigation items in the footer menu. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
FooterMenuItemsProperty	Identifies the FooterMenuItems dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
FooterMenuItemsSource	Gets or sets the object that represents the navigation items to be used in the footer menu. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
FooterMenuItemsSourceProperty	Identifies the FooterMenuItemsSource dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
Header	Gets or sets the header content. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
HeaderProperty	Identifies the Header dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
HeaderTemplate	Gets or sets the DataTemplate used to display the control's header. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
HeaderTemplateProperty	Identifies the HeaderTemplate dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
IsBackButtonVisible	Gets or sets a value that indicates whether the back button is visible or not. Default value is "Auto", which indicates that button visibility depends on the DisplayMode setting of the NavigationView. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
IsBackButtonVisibleProperty	Identifies the IsBackButtonVisible dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
IsBackEnabled	Gets or sets a value that indicates whether the back button is enabled or disabled. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
IsBackEnabledProperty	Identifies the IsBackEnabled dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
IsPaneOpen	Gets or sets a value that specifies whether the NavigationView pane is expanded to its full width. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
IsPaneOpenProperty	Identifies the IsPaneOpen dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
IsPaneToggleButtonVisible	Gets or sets a value that indicates whether the menu toggle button is shown. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
IsPaneToggleButtonVisibleProperty	Identifies the IsPaneToggleButtonVisible dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
IsPaneVisible	Gets or sets a value that determines whether the pane is shown. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
IsPaneVisibleProperty	Identifies the IsPaneVisible dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
IsSettingsVisible	Gets or sets a value that indicates whether the settings button is shown. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
IsSettingsVisibleProperty	Identifies the IsSettingsVisible dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
IsTitleBarAutoPaddingEnabled	Gets or sets a value that indicates whether top padding is added to the navigation view's header when used with a custom title bar. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
IsTitleBarAutoPaddingEnabledProperty	Identifies the IsTitleBarAutoPaddingEnabled dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
MenuItemContainerStyle	Gets or sets the style that is used when rendering the menu item containers. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
MenuItemContainerStyleProperty	Identifies the MenuItemContainerStyle dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
MenuItemContainerStyleSelector	Gets or sets a reference to a custom StyleSelector logic class. The StyleSelector returns different Style values to use for the item container based on characteristics of the object being displayed. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
MenuItemContainerStyleSelectorProperty	Identifies the MenuItemContainerStyleSelector dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
MenuItems	Gets the collection of menu items displayed in the NavigationView. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
MenuItemsProperty	Identifies the MenuItems dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
MenuItemsSource	Gets or sets an object source used to generate the content of the NavigationView menu. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
MenuItemsSourceProperty	Identifies the MenuItemsSource dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
MenuItemTemplate	Gets or sets the DataTemplate used to display each menu item. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
MenuItemTemplateProperty	Identifies the MenuItemTemplate dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
MenuItemTemplateSelector	Gets or sets a reference to a custom DataTemplateSelector logic class. The DataTemplateSelector referenced by this property returns a template to apply to items. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
MenuItemTemplateSelectorProperty	Identifies the MenuItemTemplateSelector dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
OpenPaneLength	Gets or sets the width of the NavigationView pane when it's fully expanded. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
OpenPaneLengthProperty	Identifies the OpenPaneLength dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
OverflowLabelMode	Gets or sets a value that indicates what text label is shown for the overflow menu. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
OverflowLabelModeProperty	Identifies the OverflowLabelMode dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
PaneCustomContent	Gets or sets a UI element that is shown in the NavigationView pane. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
PaneCustomContentProperty	Identifies the PaneCustomContent dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
PaneDisplayMode	Gets or sets a value that indicates how and where the NavigationView pane is shown. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
PaneDisplayModeProperty	Identifies the PaneDisplayMode dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
PaneFooter	Gets or sets the content for the pane footer. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
PaneFooterProperty	Identifies the PaneFooter dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
PaneHeader	Gets or sets the content for the pane header. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
PaneHeaderProperty	Identifies the PaneHeader dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
PaneTitle	Gets or sets the label adjacent to the menu icon when the NavigationView pane is open. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
PaneTitleProperty	Identifies the PaneTitle dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
PaneToggleButtonStyle	Gets or sets the Style that defines the look of the menu toggle button. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
PaneToggleButtonStyleProperty	Identifies the PaneToggleButtonStyle dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
SelectedItem	Gets or sets the selected item. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
SelectedItemProperty	Identifies the SelectedItem dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
SelectionFollowsFocus	Gets or sets a value that indicates whether item selection changes when keyboard focus changes. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
SelectionFollowsFocusProperty	Identifies the SelectionFollowsFocus dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
SettingsItem	Gets the navigation item that represents the entry point to app settings. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
SettingsItemProperty	Identifies the SettingsItem dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
ShoulderNavigationEnabled	Gets or sets a value that indicates when gamepad bumpers can be used to navigate the top-level navigation items in a NavigationView. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
ShoulderNavigationEnabledProperty	Identifies the ShoulderNavigationEnabled dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
TemplateSettings	Gets an object that provides calculated values that can be referenced as TemplateBinding sources when defining templates for a NavigationView control. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
TemplateSettingsProperty	Identifies the TemplateSettings dependency property. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).

Methods

Collapse(NavigationViewItem)	Collapses the specified node in the tree. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
ContainerFromMenuItem(Object)	Returns the container corresponding to the specified menu item. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
Expand(NavigationViewItem)	Expands the specified node in the tree. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
MenuItemFromContainer(DependencyObject)	Returns the item that corresponds to the specified, generated container. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).

Events

BackRequested	Occurs when the back button receives an interaction such as a click or tap. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
Collapsed	Occurs when a node in the tree is collapsed. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
DisplayModeChanged	Occurs when the DisplayMode property changes. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
Expanding	Occurs when a node in the tree starts to expand. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
ItemInvoked	Occurs when an item in the menu receives an interaction such a a click or tap. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
PaneClosed	Occurs when the NavigationView pane is closed. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
PaneClosing	Occurs when the NavigationView pane is closing. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
PaneOpened	Occurs when the NavigationView pane is opened. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
PaneOpening	Occurs when the NavigationView pane is opening. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).
SelectionChanged	Occurs when the currently selected item changes. This documentation applies to WinUI 2 for UWP (for WinUI in the Windows App SDK, see the Windows App SDK namespaces).

See also

• Guidelines for navigation view
• Back button in NavigationView