AppBar AppBar AppBar Class

Represents the container control that holds app UI components for commanding and experiences.

Important

You should use the AppBar only when you are upgrading a Universal Windows 8 app that uses the AppBar, and need to minimize changes. For new apps in Windows 10, we recommend using the CommandBar control instead.

Syntax

Declaration

public class AppBarpublic class AppBarPublic Class AppBar
<AppBar .../>
-or-
<AppBar>
  content
</AppBar>

Inheritance Hierarchy

Inherited Members

Inherited properties

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,
Tag
Tag
Tag
, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,

Inherited events

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,

Inherited methods

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,

Remarks

Important

You should use the AppBar only when you are upgrading a Universal Windows 8 app that uses the AppBar, and need to minimize changes. For new apps in Windows 10, we recommend using the CommandBar control instead.

An app bar is a UI element that's typically used to present commands and tools to the user, but can also be used for navigation. An app bar can appear at the top of the page, at the bottom of the page, or both. By default, its shown in a minimal state. Its content is shown or hidden when the user presses the ellipsis [•••], or performs a right-click that is not otherwise handled by the app.

Here's an app bar in it's minimal state.

A closed app bar control

Here's the app bar when it's open.

An open app bar control

You can open and close the app bar programmatically by setting the IsOpen property. You can use the Opening, Opened, Closing, and Closed events to respond to the app bar being opened or closed.

By default, the app bar is dismissed (closed) when the user interacts with the app anywhere outside of the app bar. Closing the app bar this way is called light dismiss. You can control how the app bar is dismissed by setting the IsSticky property. When the app bar is sticky, it's not closed by a light dismiss gesture. The app bar remains visible until the user right clicks or presses the ellipsis [•••].

To add an app bar in Extensible Application Markup Language (XAML), you assign an AppBar control to a Page 's TopAppBar or BottomAppBar property. A single app bar can be shared across multiple pages. You can add and remove commands programmatically based on the page context.

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 Styling controls. 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 available in the (Program Files)\Windows Kits\10\DesignTime\CommonConfiguration\Neutral\UAP&lt;SDK version>\Generic folder from a Windows Software Development Kit (SDK) installation. Styles and resources from different versions of the SDK might have different values.

Starting in Windows 10, version 1607 (Windows Software Development Kit (SDK) version 10.0.14393.0), generic.xaml includes resources that you can use to modify the colors of a control in different visual states without modifying the control template. In apps that target this software development kit (SDK) or later, modifying these resources is preferred to setting properties such as Background and Foreground. For more info, see the Light-weight styling section of the Styling controls article.

This table shows the resources used by the AppBar control.

Resource keyDescription
AppBarBackgroundBackground color at rest
AppBarForegroundText color at rest
AppBarHighContrastBorderBorder color for high-contrast
AppBarEllipsisButtonBackgroundBackground color of ellipsis at rest
AppBarEllipsisButtonBackgroundPointerOverBackground color of ellipsis on hover
AppBarEllipsisButtonBackgroundPressedBackground color of ellipsis when pressed
AppBarEllipsisButtonBackgroundDisabledBackground color of ellipsis when disabled
AppBarEllipsisButtonForegroundForeground color of ellipsis at rest
AppBarEllipsisButtonForegroundPointerOverForeground color of ellipsis on hover
AppBarEllipsisButtonForegroundPressedForeground color of ellipsis when pressed
AppBarEllipsisButtonForegroundDisabledForeground color of ellipsis when disabled
AppBarEllipsisButtonBorderBrushBorder color of ellipsis at rest
AppBarEllipsisButtonBorderBrushPointerOverBorder color of ellipsis on hover
AppBarEllipsisButtonBorderBrushPressedBorder color of ellipsis when pressed
AppBarEllipsisButtonBorderBrushDisabledBorder color of ellipsis when disabled

Examples

This example shows a top app bar with a group of 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>
            <AutoSuggestBox Grid.Column="1" Width="300" Height="50" HorizontalAlignment="Right"/>
        </Grid>
    </AppBar>
</Page.TopAppBar>

Constructors summary

Initializes a new instance of the AppBar class.

Properties summary

Gets or sets a value that indicates whether icon buttons are displayed when the app bar is not completely open.

Identifies the ClosedDisplayMode dependency property.

Gets or sets a value that indicates whether the AppBar is open.

Identifies the IsOpen dependency property.

Gets or sets a value that indicates whether the AppBar does not close on light dismiss.

Identifies the IsSticky dependency property.

Gets or sets a value that specifies whether the area outside of a light-dismiss UI is darkened.

Identifies the LightDismissOverlayMode dependency property.

Gets an object that provides calculated values that can be referenced as {TemplateBinding} markup extension sources when defining templates for an AppBar control.

Methods summary

Invoked when the AppBar changes from visible to hidden.

Invoked when the AppBar starts to change from visible to hidden.

Invoked when the AppBar changes from hidden to visible, or is first displayed.

Invoked when the AppBar starts to change from hidden to visible, or starts to be first displayed.

Events summary

Occurs when the AppBar changes from visible to hidden.

Occurs when the AppBar starts to change from visible to hidden.

Occurs when the AppBar changes from hidden to visible.

Occurs when the AppBar starts to change from hidden to visible.

Constructors

  • AppBar()
    AppBar()
    AppBar()
    AppBar()

    Initializes a new instance of the AppBar class.

    public AppBar()public New()Public Sub New()public AppBar()

Properties

  • ClosedDisplayMode
    ClosedDisplayMode
    ClosedDisplayMode
    ClosedDisplayMode

    Gets or sets a value that indicates whether icon buttons are displayed when the app bar is not completely open.

    public AppBarClosedDisplayMode ClosedDisplayMode { get; set; }public AppBarClosedDisplayMode ClosedDisplayMode { get; set; }Public ReadWrite Property ClosedDisplayMode As AppBarClosedDisplayModepublic AppBarClosedDisplayMode ClosedDisplayMode { get; set; }
    <AppBar ClosedDisplayMode="Compact"/>
    -or-
    <AppBar ClosedDisplayMode="Minimal"/>
    

    Property Value

  • ClosedDisplayModeProperty
    ClosedDisplayModeProperty
    ClosedDisplayModeProperty
    ClosedDisplayModeProperty

    Identifies the ClosedDisplayMode dependency property.

    public static DependencyProperty ClosedDisplayModeProperty { get; }public static DependencyProperty ClosedDisplayModeProperty { get; }Public Static ReadOnly Property ClosedDisplayModeProperty As DependencyPropertypublic static DependencyProperty ClosedDisplayModeProperty { get; }

    Property Value

  • IsOpen
    IsOpen
    IsOpen
    IsOpen

    Gets or sets a value that indicates whether the AppBar is open.

    public bool IsOpen { get; set; }public bool IsOpen { get; set; }Public ReadWrite Property IsOpen As boolpublic bool IsOpen { get; set; }
    <AppBar IsOpen="bool"/>
    

    Property Value

    • bool
      bool
      bool

      true if the app bar is open; otherwise, false.

    Remarks

    How the app bar is displayed when it's open depends on the ClosedDisplayMode property setting. For more info, see App bar and command bar.

    You can open and close the app bar programmatically by setting the IsOpen property. You can use the Opening, Opened, Closing, and Closed events to respond to the app bar being opened or closed.

    Notes for previous versions

    Windows 8 Binding to the IsOpen property doesn't have the expected results because the INotifyPropertyChanged notification doesn't occur when the property is set.

    Examples

    <AppBar IsOpen="True">
        <Grid>
            <StackPanel Orientation="Horizontal" HorizontalAlignment="Right">
                <Button Style="{StaticResource PreviousAppBarButtonStyle}" 
                        Click="Button_Click"/>
                <Button Style="{StaticResource NextAppBarButtonStyle}" 
                        Click="Button_Click"/>
            </StackPanel>
        </Grid>
    </AppBar>
    
  • IsOpenProperty
    IsOpenProperty
    IsOpenProperty
    IsOpenProperty

    Identifies the IsOpen dependency property.

    public static DependencyProperty IsOpenProperty { get; }public static DependencyProperty IsOpenProperty { get; }Public Static ReadOnly Property IsOpenProperty As DependencyPropertypublic static DependencyProperty IsOpenProperty { get; }

    Property Value

  • IsSticky
    IsSticky
    IsSticky
    IsSticky

    Gets or sets a value that indicates whether the AppBar does not close on light dismiss.

    public bool IsSticky { get; set; }public bool IsSticky { get; set; }Public ReadWrite Property IsSticky As boolpublic bool IsSticky { get; set; }
    <AppBar IsSticky="bool" .../>
    

    Property Value

    • bool
      bool
      bool

      true if the AppBar does not close on light dismiss. false if the AppBar is hidden on light dismiss.

    Remarks

    By default, app bars are dismissed when the user interacts with your app anywhere outside of the app bar. This is called light dismiss. 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.

    Examples

    <AppBar IsSticky="True">
        <Grid>
            <StackPanel Orientation="Horizontal" HorizontalAlignment="Right">
            <Button Style="{StaticResource HelpAppBarButtonStyle}" 
                    Click="Button_Click"/>
            </StackPanel>
        </Grid>
    </AppBar>
    
  • IsStickyProperty
    IsStickyProperty
    IsStickyProperty
    IsStickyProperty

    Identifies the IsSticky dependency property.

    public static DependencyProperty IsStickyProperty { get; }public static DependencyProperty IsStickyProperty { get; }Public Static ReadOnly Property IsStickyProperty As DependencyPropertypublic static DependencyProperty IsStickyProperty { get; }

    Property Value

  • LightDismissOverlayMode
    LightDismissOverlayMode
    LightDismissOverlayMode
    LightDismissOverlayMode

    Gets or sets a value that specifies whether the area outside of a light-dismiss UI is darkened.

    public LightDismissOverlayMode LightDismissOverlayMode { get; set; }public LightDismissOverlayMode LightDismissOverlayMode { get; set; }Public ReadWrite Property LightDismissOverlayMode As LightDismissOverlayModepublic LightDismissOverlayMode LightDismissOverlayMode { get; set; }
    <appBar LightDismissOverlayMode="lightDismissOverlayModeMemberName" />
    

    Property Value

    Remarks

    Transient UI, such as a MenuFlyout or secondary menu in a command bar, closes when you click or tap outside of it. This is called light-dismiss. "Overlay" refers to the area outside of a light-dismiss UI.

    By default, the "overlay" is darkened on the Xbox, and not darkened on other devices families. You can set LightDismissOverlayMode to On to make your app darken the "overlay" area on all device families, or set it to Off to not darken the "overlay" area on all device families.

    Version compatibility

    The LightDismissOverlayMode property is not available prior to Windows 10, version 1607. If your app’s 'minimum platform version' setting in Microsoft Visual Studio is less than the 'introduced version' shown in the Requirements block later in this page, you must design and test your app to account for this. For more info, see Version adaptive code.

    To avoid exceptions when your app runs on previous versions of Windows 10, do not set this property in XAML or use it without performing a runtime check. This example shows how to use the ApiInformation class to check for the presence of this property before you set it.

    <CommandBar x:Name="commandBar1" Loaded="CommandBar_Loaded"/>
    
    private void CommandBar_Loaded(object sender, RoutedEventArgs e)
    {
        if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Controls.AppBar", "LightDismissOverlayMode"))
        {
            commandBar1.LightDismissOverlayMode = LightDismissOverlayMode.On;
        }
    }
    
  • LightDismissOverlayModeProperty
    LightDismissOverlayModeProperty
    LightDismissOverlayModeProperty
    LightDismissOverlayModeProperty

    Identifies the LightDismissOverlayMode dependency property.

    public static DependencyProperty LightDismissOverlayModeProperty { get; }public static DependencyProperty LightDismissOverlayModeProperty { get; }Public Static ReadOnly Property LightDismissOverlayModeProperty As DependencyPropertypublic static DependencyProperty LightDismissOverlayModeProperty { get; }

    Property Value

  • TemplateSettings
    TemplateSettings
    TemplateSettings
    TemplateSettings

    Gets an object that provides calculated values that can be referenced as {TemplateBinding} markup extension sources when defining templates for an AppBar control.

    public AppBarTemplateSettings TemplateSettings { get; }public AppBarTemplateSettings TemplateSettings { get; }Public ReadOnly Property TemplateSettings As AppBarTemplateSettingspublic AppBarTemplateSettings TemplateSettings { get; }

    Property Value

Methods

  • OnClosed(Object)
    OnClosed(Object)
    OnClosed(Object)
    OnClosed(Object)

    Invoked when the AppBar changes from visible to hidden.

    protected virtual void OnClosed(Object e)protected virtual void OnClosed(Object e)Protected Overridable Function OnClosed(e As Object) As voidprotected virtual void OnClosed(Object e)

    Parameters

    • e
      System.Object
      System.Object
      System.Object

      Event data for the event.

  • OnClosing(Object)
    OnClosing(Object)
    OnClosing(Object)
    OnClosing(Object)

    Invoked when the AppBar starts to change from visible to hidden.

    protected virtual void OnClosing(Object e)protected virtual void OnClosing(Object e)Protected Overridable Function OnClosing(e As Object) As voidprotected virtual void OnClosing(Object e)

    Parameters

    • e
      System.Object
      System.Object
      System.Object

      Event data for the event.

  • OnOpened(Object)
    OnOpened(Object)
    OnOpened(Object)
    OnOpened(Object)

    Invoked when the AppBar changes from hidden to visible, or is first displayed.

    protected virtual void OnOpened(Object e)protected virtual void OnOpened(Object e)Protected Overridable Function OnOpened(e As Object) As voidprotected virtual void OnOpened(Object e)

    Parameters

    • e
      System.Object
      System.Object
      System.Object

      Event data for the event.

  • OnOpening(Object)
    OnOpening(Object)
    OnOpening(Object)
    OnOpening(Object)

    Invoked when the AppBar starts to change from hidden to visible, or starts to be first displayed.

    protected virtual void OnOpening(Object e)protected virtual void OnOpening(Object e)Protected Overridable Function OnOpening(e As Object) As voidprotected virtual void OnOpening(Object e)

    Parameters

    • e
      System.Object
      System.Object
      System.Object

      Event data for the event.

Events

  • Closed
    Closed
    Closed
    Closed

    Occurs when the AppBar changes from visible to hidden.

    public event EventHandler Closedpublic event EventHandler ClosedPublic Event Closedpublic event EventHandler Closed
    <AppBar Closed="eventhandler"/>
    

    Remarks

    You can respond to the app bar being dismissed by handling the Closed event.

  • Closing
    Closing
    Closing
    Closing

    Occurs when the AppBar starts to change from visible to hidden.

    public event EventHandler Closingpublic event EventHandler ClosingPublic Event Closingpublic event EventHandler Closing
    <AppBar Closing="eventhandler"/>
    
  • Opened
    Opened
    Opened
    Opened

    Occurs when the AppBar changes from hidden to visible.

    public event EventHandler Openedpublic event EventHandler OpenedPublic Event Openedpublic event EventHandler Opened
    <AppBar Opened="eventhandler"/>
    

    Remarks

    You can respond to the app bar being opened by handling the Opened event.

  • Opening
    Opening
    Opening
    Opening

    Occurs when the AppBar starts to change from hidden to visible.

    public event EventHandler Openingpublic event EventHandler OpeningPublic Event Openingpublic event EventHandler Opening
    <AppBar Opening="eventhandler"/>
    

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ComposableAttribute
Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.ThreadingAttribute
Windows.Foundation.Metadata.WebHostHiddenAttribute

Details

Assembly

Windows.UI.Xaml.Controls.dll