Quickstart: adding app bars (XAML)
[ This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation ]
Use app bars to show navigation, commands, and tools that can be hidden away when they aren't needed. You can put an app bar at the top of the page, at the bottom of the page, or both. App bars are hidden by default, and are shown or dismissed when the user right-clicks, presses Windows+Z, or swipes from the top or bottom edge of the screen. They can be shown programmatically when the user makes a selection or interacts with the app.
See this feature in action as part of our App features, start to finish series: Windows Store app UI, start to finish
Prerequisites
- We assume that you can add controls to a basic Windows Store app using C++, C#, or Visual Basic. For instructions on adding a control, see Quickstart: Adding controls and handling events.
- Review Commanding design for Windows Store apps.
Choose an AppBar or CommandBar
The XAML framework provides the CommandBar and AppBar controls to display UI that appears at the top or bottom edge of the screen on an edge swipe. The CommandBar has more built-in functionality, but is limited in the kinds of content you can put in it. The AppBar allows you to add any Extensible Application Markup Language (XAML) content to it, but you have to manage layout and resizing yourself.
Important The CommandBar, AppBarButton, AppBarToggleButton , and AppBarSeparator controls are available only for apps that target Windows 8.1. In apps that target Windows 8, you must use an AppBar control.
If you need an app bar that contains only AppBarButton, AppBarToggleButton , and AppBarSeparator controls, use a CommandBar. The CommandBar simplifies the creation of basic app bars by providing:
- Automatic layout of commands, with primary commands on the right and secondary commands on the left.
- Automatic resizing of app bar commands when the app size changes.
If you need more complex content, such as images, progress bars, a search box, text blocks, and custom-styled buttons, use an AppBar control. You can use an AppBar with custom content to create a bar of tools or navigation UI. When you put your commands in a AppBar control, you have to resize and rearrange the AppBar content as the screen size changes. For more info, see How to use an app bar in different views.
Adding an app bar
To add an app bar to your app, assign a CommandBar or AppBar control to the TopAppBar or BottomAppBar property of a Page.
Use the navigation (top app) bar to show navigation in your app. You will typically use an AppBar with custom-styled buttons for navigation. For more info, see Navigation design for Windows Store apps.
Use the bottom app bar to show commands and tools. For more info, see Commanding design for Windows Store apps.
This example shows how to add an AppBar control as the top app bar, and a CommandBar control as the bottom app bar.
<Page.TopAppBar> <AppBar> <!-- AppBar content --> </AppBar> </Page.TopAppBar> <Page.BottomAppBar> <CommandBar> <!-- CommandBar content --> </CommandBar> </Page.BottomAppBar>
In a multi-page app, you can share app bars with common commands across pages. For more info, see How to share an app bar across pages.
Adding content to a CommandBar
To add content to a CommandBar, add AppBarButton, AppBarToggleButton , and AppBarSeparator controls to the PrimaryCommands and SecondaryCommands collections of the CommandBar. Controls added directly to the CommandBar in XAML are added to the PrimaryCommands collection automatically.
This example shows a CommandBar with PrimaryCommands and SecondaryCommands.
<Page.BottomAppBar> <CommandBar> <AppBarButton Label="Refresh" Icon="Refresh" Click="AppBarButton_Click"/> <AppBarButton Label="Help" Icon="Help" Click="AppBarButton_Click"/> <CommandBar.SecondaryCommands> <AppBarButton Label="Edit" Icon="Edit" Click="AppBarButton_Click"/> <AppBarButton Label="Remove" Icon="Remove" Click="AppBarButton_Click"/> <AppBarButton Label="Add" Icon="Add" Click="AppBarButton_Click"/> </CommandBar.SecondaryCommands> </CommandBar> </Page.BottomAppBar>.png)
Adding content to an AppBar
An AppBar can only contain one piece of child content, so you typically add a layout panel that you can add other controls to.
This example shows an AppBar with navigation buttons and a search box.
<Page.TopAppBar> <AppBar> <Grid> <Grid.ColumnDefinitions> <ColumnDefinition/> <ColumnDefinition/> </Grid.ColumnDefinitions> <StackPanel Orientation="Horizontal"> <Button Content="Home" Width="140" Height="80" Click="AppBarButton_Click"/> <Button Content="Page 1" Width="140" Height="80" Click="AppBarButton_Click"/> <Button Content="Page 2" Width="140" Height="80" Click="AppBarButton_Click"/> </StackPanel> <SearchBox Grid.Column="1" Width="300" Height="50" HorizontalAlignment="Right"/> </Grid> </AppBar> </Page.TopAppBar>
Opening an app bar programmatically
By default, app bars appear when the user right-clicks, or presses Windows+Z, or swipes from the top or bottom edge of the screen. When the user performs one of these actions, both the top and bottom app bars appear, if the page has both. You can open an app bar programmatically by setting the IsOpen property to true. When you do this, only the specific app bar you set the property value for (top or bottom) is opened.
To initially open your app bar when the page is loaded, set the IsOpen property to true in your XAML.
<Page.BottomAppBar> <CommandBar IsOpen="True"> <AppBarButton Label="Refresh" Icon="Refresh" Click="AppBarButton_Click"/> <AppBarButton Label="Help" Icon="Help" Click="AppBarButton_Click"/> </CommandBar> </Page.BottomAppBar>To open the app bar programmatically, set the IsOpen property to true in your code. To reference the app bar in code, you can give it a name and reference it by name, or you can reference the TopAppBar or BottomAppBar property.
private void OpenButton_Click(object sender, RoutedEventArgs e) { if (this.BottomAppBar != null) { this.BottomAppBar.IsOpen = true; } }You typically open the app bar programmatically to show contextual commands when the user interacts with an item in your app. For example, you might show an app bar with formatting commands when the user selects text in your app. When you show contextual commands, set the app bar dismissal mode to sticky until the context changes to keep the commands visible.
Making an app bar sticky
By default, app bars are dismissed when the user interacts with your app anywhere outside of the app bar. To keep commands visible, you can change the dismissal mode by setting the IsSticky property to true. When an app bar is sticky, it's dismissed only when the user right-clicks, presses Windows+Z, or swipes from the top or bottom edge of the screen.
To make your app bar remain visible when the user interacts with your app, set the IsSticky property to true in your XAML.
<Page.TopAppBar> <AppBar IsSticky="True"> <StackPanel Orientation="Horizontal"> <Button Content="Home" Width="140" Height="80" Click="AppBarButton_Click"/> <Button Content="Page 1" Width="140" Height="80" Click="AppBarButton_Click"/> <Button Content="Page 2" Width="140" Height="80" Click="AppBarButton_Click"/> </StackPanel> </AppBar> </Page.TopAppBar>To change the app bar dismissal mode programmatically, set the IsSticky property to true in your code. To reference the app bar in code, you can give it a name and reference it by name, or you can reference the TopAppBar or BottomAppBar property.
private void OpenButton_Click(object sender, RoutedEventArgs e) { if (this.TopAppBar != null) { this.TopAppBar.IsSticky = true; } }
Summary and next steps
In this quickstart, you learned how to add an app bar to your Windows Store app using C++, C#, or Visual Basic.
To provide a consistent experience for your users, review the Guidelines for app bars.
To learn more about AppBarButton controls, see Quickstart: Adding app bar buttons.
Related topics
Quickstart: Adding app bar buttons