CommandBar
CommandBar
CommandBar
CommandBar
Class
Definition
Represents a specialized app bar that provides layout for AppBarButton and related command elements.
public : class CommandBar : AppBar, ICommandBar, ICommandBar2, ICommandBar3public class CommandBar : AppBar, ICommandBar, ICommandBar2, ICommandBar3Public Class CommandBar Inherits AppBar Implements ICommandBar, ICommandBar2, ICommandBar3// This API is not available in Javascript.
<CommandBar .../>
-or-
<CommandBar>
commandBarElements
</CommandBar>
- Inheritance
-
CommandBarCommandBarCommandBarCommandBar
- Attributes
| Device family |
Windows 10 (introduced v10.0.10240.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v1)
|
Inherited Members
Inherited properties
Inherited events
Inherited methods
Examples
This example creates the command bar shown previously.
<CommandBar>
<AppBarToggleButton Icon="Shuffle" Label="Shuffle" Click="AppBarButton_Click"/>
<AppBarToggleButton Icon="RepeatAll" Label="Repeat" Click="AppBarButton_Click"/>
<AppBarSeparator/>
<AppBarButton Icon="Back" Label="Back" Click="AppBarButton_Click"/>
<AppBarButton Icon="Stop" Label="Stop" Click="AppBarButton_Click"/>
<AppBarButton Icon="Play" Label="Play" Click="AppBarButton_Click"/>
<AppBarButton Icon="Forward" Label="Forward" Click="AppBarButton_Click"/>
<CommandBar.SecondaryCommands>
<AppBarButton Icon="Like" Label="Like" Click="AppBarButton_Click"/>
<AppBarButton Icon="Dislike" Label="Dislike" Click="AppBarButton_Click"/>
</CommandBar.SecondaryCommands>
<CommandBar.Content>
<TextBlock Text="Now playing..." Margin="12,14"/>
</CommandBar.Content>
</CommandBar>
Remarks
Use a CommandBar to provide users with quick access to your app’s most common tasks. It's a general-purpose, flexible, light-weight control that can display both complex content, such as images, progress bars, or text blocks, as well as simple commands such as AppBarButton, AppBarToggleButton, and AppBarSeparator controls.
Anatomy
By default, the CommandBar shows a row of icon buttons and a "More" button, which is represented by an ellipsis [•••]. Here's the CommandBar created by the example code shown later. It's shown in its default closed state.
Here's the same CommandBar shown in its open state. The labels show the main parts of the control.
The CommandBar is divided into 4 main areas:
- The content area is shown on the left.
- The "More" button is shown on the right. Pressing the "More" button has 2 effects: it reveals the labels on the primary command buttons, and it opens the overflow menu if any secondary commands are present.
- The primary commands are shown to the left of the "More" button.
- The overflow menu is shown only when the CommandBar is open and contains secondary commands.
The layout is reversed when the FlowDirection is RightToLeft.
Content and commands
CommandBar has 3 properties you can use to add content and commands: Content, PrimaryCommands, and SecondaryCommands.
You can add any XAML elements to the content area by setting the Content property.
Both the PrimaryCommands and SecondaryCommands can be populated only with AppBarButton, AppBarToggleButton, and AppBarSeparator command elements. By default, items you add to the CommandBar are added to the PrimaryCommands collection. These commands are shown to the left of the "More" button. You can add commands to the SecondaryCommands collection, and these items are shown in the overflow menu. You can programmatically move commands between the PrimaryCommands and SecondaryCommands as needed.
The app bar button controls are characterized by an icon and associated label. They have two sizes; normal and compact. By default, the text label is shown. When the IsCompact property is set to true, the text label is hidden. When used in a CommandBar control, the CommandBar sets the IsCompact property automatically as the control is opened and closed.
If the width of a button needs to be greater than the default when shown in the PrimaryCommands, use the MinWidth property to achieve the desired size. Then, if you later move it to the SecondaryCommands, it will still stretch to fill the width of the overflow menu.
If a text label for an app bar button is too long to fit on one line it will wrap to another line, increasing the overall height of the bar when it’s opened. You can include a soft-hyphen character (0x00AD) in the text for a label to hint at the character boundary where a word break should occur. In XAML, you express this using an escape sequence, like this:
<AppBarButton Icon="Back" Label="Areally­longlabel"/>
When the label wraps at the hinted location, it looks like this.

Open and closed states
The CommandBar can be open or closed. A user can switch between these states by pressing the "More" button. You can switch between them programmatically by setting the IsOpen property. You can use the Opening, Opened, Closing, and Closed events to respond to the CommandBar being opened or closed.
When open, the primary command buttons are shown with text labels and the overflow menu is open if secondary commands are present. The default overflow menu is styled to be distinct from the bar. You can adjust the styling by setting the CommandBarOverflowPresenterStyle property to a Style that targets the CommandBarOverflowPresenter.
You can control how the CommandBar is shown in its closed state by setting the ClosedDisplayMode property. By default, it’s shown in the Compact mode, with content, icons without labels, and the "More" button. You can set the mode to Minimal to show only a thin bar that acts as the "More" button. In Minimal mode, the user can press anywhere on the bar to open it. Here's how the CommandBar looks in Minimal mode.
Changing the ClosedDisplayMode to provide more or less of a hint to the user affects the layout of surrounding elements. When the CommandBar transitions between closed and open, it does not affect the layout of other elements.
IsSticky
After opening the CommandBar, if the user interacts with the app anywhere outside of the control then by default the overflow menu is dismissed and the labels are hidden. Closing it in this way is called light dismiss. You can control how the bar is dismissed by setting the IsSticky property. When the bar is sticky (IsSticky ="true "), it's not closed by a light dismiss gesture. The app bar remains visible until the user presses the "More" button or, if present, selects an item from the overflow menu.
Placement
You can place a CommandBar inline with your app content, anywhere in your XAML. If the CommandBar must remain visible to a user when the touch keyboard, or Soft Input Panel (SIP), appears then you can assign it to the BottomAppBar property of a Page and it will move to remain visible when the Soft Input Panel (SIP) is present. Otherwise, you should place it inline and positioned relative to your app content. Where you place the CommandBar will influence things like whether you make it sticky, or use the minimal mode when it's closed. For more info and guidance, see Guidelines for command bars.
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<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 CommandBar control.
| Resource key | Description |
|---|---|
| CommandBarBackground | Background color at rest |
| CommandBarForeground | Text color at rest |
| CommandBarHighContrastBorder | Border color for high-contrast |
| CommandBarEllipsisIconForegroundDisabled | Color of ellipsis icon when disabled |
| AppBarEllipsisButtonBackground | Background color of ellipsis at rest |
| AppBarEllipsisButtonBackgroundPointerOver | Background color of ellipsis on hover |
| AppBarEllipsisButtonBackgroundPressed | Background color of ellipsis when pressed |
| AppBarEllipsisButtonBackgroundDisabled | Background color of ellipsis when disabled |
| AppBarEllipsisButtonForeground | Foreground color of ellipsis at rest |
| AppBarEllipsisButtonForegroundPointerOver | Foreground color of ellipsis on hover |
| AppBarEllipsisButtonForegroundPressed | Foreground color of ellipsis when pressed |
| AppBarEllipsisButtonForegroundDisabled | Foreground color of ellipsis when disabled |
| AppBarEllipsisButtonBorderBrush | Border color of ellipsis at rest |
| AppBarEllipsisButtonBorderBrushPointerOver | Border color of ellipsis on hover |
| AppBarEllipsisButtonBorderBrushPressed | Border color of ellipsis when pressed |
| AppBarEllipsisButtonBorderBrushDisabled | Border color of ellipsis when disabled |
Constructors
CommandBar() CommandBar() CommandBar() CommandBar()
Initializes a new instance of the CommandBar class.
public : CommandBar()public CommandBar()Public Sub New()// This API is not available in Javascript.
Properties
CommandBarOverflowPresenterStyle CommandBarOverflowPresenterStyle CommandBarOverflowPresenterStyle CommandBarOverflowPresenterStyle
Gets or sets the Style applied to the overflow content of the CommandBar.
public : Style CommandBarOverflowPresenterStyle { get; set; }public Style CommandBarOverflowPresenterStyle { get; set; }Public ReadWrite Property CommandBarOverflowPresenterStyle As Style// This API is not available in Javascript.
<CommandBar CommandBarOverflowPresenterStyle={StaticResource styleResourceKey}/>
The applied Style for the overflow content of the CommandBar, if present; otherwise, null. The default is null.
Remarks
The Style element you use for a CommandBarOverflowPresenter value must specify TargetType="CommandBarOverflowPresenter".
You can style the properties of the internal CommandBarOverflowPresenter that is presenting the overflow content (SecondaryCommands ) of a CommandBar. The properties that can be styled are the dependency properties of the base ItemsControl class or Control class, such as FontSize or Padding, or base element properties such as FrameworkElement.Margin that the CommandBarOverflowPresenter class inherits.
- See Also
CommandBarOverflowPresenterStyleProperty CommandBarOverflowPresenterStyleProperty CommandBarOverflowPresenterStyleProperty CommandBarOverflowPresenterStyleProperty
Identifies the CommandBarOverflowPresenterStyle dependency property.
public : static DependencyProperty CommandBarOverflowPresenterStyleProperty { get; }public static DependencyProperty CommandBarOverflowPresenterStyleProperty { get; }Public Static ReadOnly Property CommandBarOverflowPresenterStyleProperty As DependencyProperty// This API is not available in Javascript.
The identifier for the CommandBarOverflowPresenterStyle dependency property.
CommandBarTemplateSettings CommandBarTemplateSettings CommandBarTemplateSettings CommandBarTemplateSettings
Gets an object that provides calculated values that can be referenced as {TemplateBinding} markup extension sources when defining templates for a CommandBar control.
public : CommandBarTemplateSettings CommandBarTemplateSettings { get; }public CommandBarTemplateSettings CommandBarTemplateSettings { get; }Public ReadOnly Property CommandBarTemplateSettings As CommandBarTemplateSettings// This API is not available in Javascript.
- Value
- CommandBarTemplateSettings CommandBarTemplateSettings CommandBarTemplateSettings CommandBarTemplateSettings
An object that provides calculated values for templates.
DefaultLabelPosition DefaultLabelPosition DefaultLabelPosition DefaultLabelPosition
Gets or sets a value that indicates the placement and visibility of the labels on the command bar's buttons.
public : CommandBarDefaultLabelPosition DefaultLabelPosition { get; set; }public CommandBarDefaultLabelPosition DefaultLabelPosition { get; set; }Public ReadWrite Property DefaultLabelPosition As CommandBarDefaultLabelPosition// This API is not available in Javascript.
<CommandBar DefaultLabelPosition="commandBarDefaultLabelPositionMemberName" />
- Value
- CommandBarDefaultLabelPosition CommandBarDefaultLabelPosition CommandBarDefaultLabelPosition CommandBarDefaultLabelPosition
An enumeration value that indicates the placement and visibility of the labels on the command bar's buttons. The default is Bottom.
| Device family |
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v3)
|
Remarks
By default, an app bar button's label is displayed below the icon. You can set this property to show labels to the right of the icon, or to hide labels.
You can set the AppBarButton.LabelPosition property to override this value and make the label always collapsed for a specific app bar button.
Version compatibility
The DefaultLabelPosition 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">
...
</CommandBar>
private void CommandBar_Loaded(object sender, RoutedEventArgs e)
{
if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Controls.CommandBar", "DefaultLabelPosition"))
{
commandBar1.DefaultLabelPosition = CommandBarDefaultLabelPosition.Right;
}
}
DefaultLabelPositionProperty DefaultLabelPositionProperty DefaultLabelPositionProperty DefaultLabelPositionProperty
Identifies the DefaultLabelPosition dependency property.
public : static DependencyProperty DefaultLabelPositionProperty { get; }public static DependencyProperty DefaultLabelPositionProperty { get; }Public Static ReadOnly Property DefaultLabelPositionProperty As DependencyProperty// This API is not available in Javascript.
The identifier for the DefaultLabelPosition dependency property.
| Device family |
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v3)
|
IsDynamicOverflowEnabled IsDynamicOverflowEnabled IsDynamicOverflowEnabled IsDynamicOverflowEnabled
Gets or sets a value that indicates whether primary commands automatically move to the overflow menu when space is limited.
public : PlatForm::Boolean IsDynamicOverflowEnabled { get; set; }public bool IsDynamicOverflowEnabled { get; set; }Public ReadWrite Property IsDynamicOverflowEnabled As bool// This API is not available in Javascript.
<CommandBar IsDynamicOverflowEnabled="bool"/>
- Value
- PlatForm::Boolean bool bool bool
true if primary commands automatically move to the overflow menu when space is limited; otherwise, false. The default is true.
| Device family |
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v3)
|
Remarks
For more info and guidelines, see the App bar and command bar article.
Starting in Windows 10, version 1607, CommandBar introduces a dynamic overflow feature. By default, PrimaryCommands automatically move in or out of the overflow area as the command bar width changes, for example, when users resize their app window. You can set the IsDynamicOverflowEnabled property to false to disable this behavior.
Dynamic overflow affects only the UI presentation of the commands, it doesn’t move commands from the PrimaryCommands collection to SecondaryCommands.
Version compatibility
The IsDynamicOverflowEnabled 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.
Note
Dynamic overflow is available when your app is compiled for Windows 10, version 1607 and running on version 1607 (or later). Dynamic overflow is not available when your app is compiled for a previous version or is running on a previous version.
To avoid exceptions when your app runs on previous versions of Windows 10, do not use this property without first performing a runtime check. This example shows how to use the ApiInformation class to check for the presence of this property before you use it.
<CommandBar x:Name="commandBar1" Loaded="CommandBar_Loaded">
...
</CommandBar>
private void CommandBar_Loaded(object sender, RoutedEventArgs e)
{
if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Controls.CommandBar", "IsDynamicOverflowEnabled"))
{
commandBar1.IsDynamicOverflowEnabled = true;
}
}
IsDynamicOverflowEnabledProperty IsDynamicOverflowEnabledProperty IsDynamicOverflowEnabledProperty IsDynamicOverflowEnabledProperty
Identifies the IsDynamicOverflowEnabled dependency property.
public : static DependencyProperty IsDynamicOverflowEnabledProperty { get; }public static DependencyProperty IsDynamicOverflowEnabledProperty { get; }Public Static ReadOnly Property IsDynamicOverflowEnabledProperty As DependencyProperty// This API is not available in Javascript.
The identifier for the IsDynamicOverflowEnabled dependency property.
| Device family |
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v3)
|
OverflowButtonVisibility OverflowButtonVisibility OverflowButtonVisibility OverflowButtonVisibility
Gets or sets a value that indicates when a command bar's overflow button is shown.
public : CommandBarOverflowButtonVisibility OverflowButtonVisibility { get; set; }public CommandBarOverflowButtonVisibility OverflowButtonVisibility { get; set; }Public ReadWrite Property OverflowButtonVisibility As CommandBarOverflowButtonVisibility// This API is not available in Javascript.
<CommandBar OverflowButtonVisibility="commandBarOverflowButtonVisibilityMemberName" />
- Value
- CommandBarOverflowButtonVisibility CommandBarOverflowButtonVisibility CommandBarOverflowButtonVisibility CommandBarOverflowButtonVisibility
An enumeration value that indicates when a command bar's overflow button is shown. The default is Auto.
| Device family |
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v3)
|
OverflowButtonVisibilityProperty OverflowButtonVisibilityProperty OverflowButtonVisibilityProperty OverflowButtonVisibilityProperty
Identifies the OverflowButtonVisibility dependency property.
public : static DependencyProperty OverflowButtonVisibilityProperty { get; }public static DependencyProperty OverflowButtonVisibilityProperty { get; }Public Static ReadOnly Property OverflowButtonVisibilityProperty As DependencyProperty// This API is not available in Javascript.
The identifier for the OverflowButtonVisibility dependency property.
| Device family |
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v3)
|
PrimaryCommands PrimaryCommands PrimaryCommands PrimaryCommands
Gets the collection of primary command elements for the CommandBar.
public : IObservableVector<ICommandBarElement> PrimaryCommands { get; }public IObservableVector<ICommandBarElement> PrimaryCommands { get; }Public ReadOnly Property PrimaryCommands As IObservableVector<ICommandBarElement>// This API is not available in Javascript.
<CommandBar>
<CommandBar.PrimaryCommands>
commandBarElements
</CommandBar.PrimaryCommands>
</CommandBar>
- Value
- IObservableVector<ICommandBarElement> IObservableVector<ICommandBarElement> IObservableVector<ICommandBarElement> IObservableVector<ICommandBarElement>
The collection of primary command elements for the CommandBar. The default is an empty collection.
Remarks
The PrimaryCommands collection can contain only AppBarButton, AppBarToggleButton, or AppBarSeparator command elements. The primary commands are shown on the right side of the CommandBar, to the left of the More button (...) when the FlowDirection is LeftToRight. The layout is reversed when the FlowDirection is RightToLeft.
- See Also
PrimaryCommandsProperty PrimaryCommandsProperty PrimaryCommandsProperty PrimaryCommandsProperty
Identifies the PrimaryCommands dependency property.
public : static DependencyProperty PrimaryCommandsProperty { get; }public static DependencyProperty PrimaryCommandsProperty { get; }Public Static ReadOnly Property PrimaryCommandsProperty As DependencyProperty// This API is not available in Javascript.
The identifier for the PrimaryCommands dependency property.
SecondaryCommands SecondaryCommands SecondaryCommands SecondaryCommands
Gets the collection of secondary command elements for the CommandBar.
public : IObservableVector<ICommandBarElement> SecondaryCommands { get; }public IObservableVector<ICommandBarElement> SecondaryCommands { get; }Public ReadOnly Property SecondaryCommands As IObservableVector<ICommandBarElement>// This API is not available in Javascript.
<CommandBar>
<CommandBar.SecondaryCommands>
commandBarElements
</CommandBar.SecondaryCommands>
</CommandBar>
- Value
- IObservableVector<ICommandBarElement> IObservableVector<ICommandBarElement> IObservableVector<ICommandBarElement> IObservableVector<ICommandBarElement>
The collection of secondary command elements for the CommandBar. The default is an empty collection.
Remarks
The SecondaryCommands collection can contain only AppBarButton, AppBarToggleButton, or AppBarSeparator command elements. The secondary commands are shown in the overflow menu when the CommandBar is open.
- See Also
SecondaryCommandsProperty SecondaryCommandsProperty SecondaryCommandsProperty SecondaryCommandsProperty
Identifies the SecondaryCommands dependency property.
public : static DependencyProperty SecondaryCommandsProperty { get; }public static DependencyProperty SecondaryCommandsProperty { get; }Public Static ReadOnly Property SecondaryCommandsProperty As DependencyProperty// This API is not available in Javascript.
The identifier for the SecondaryCommands dependency property.
Events
DynamicOverflowItemsChanging DynamicOverflowItemsChanging DynamicOverflowItemsChanging DynamicOverflowItemsChanging
Occurs when items move into or out of the overflow menu.
public : event TypedEventHandler DynamicOverflowItemsChanging<CommandBar, DynamicOverflowItemsChangingEventArgs>public event TypedEventHandler DynamicOverflowItemsChanging<CommandBar, DynamicOverflowItemsChangingEventArgs>Public Event DynamicOverflowItemsChanging<CommandBar, DynamicOverflowItemsChangingEventArgs>// This API is not available in Javascript.
<CommandBar DynamicOverflowItemsChanging="eventhandler"/>
| Device family |
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v3)
|
Remarks
For event data, see DynamicOverflowItemsChangingEventArgs.
Starting in Windows 10, version 1607, CommandBar introduces a dynamic overflow feature. By default, PrimaryCommands automatically move in or out of the overflow area as the command bar width changes, for example, when users resize their app window. You can set the IsDynamicOverflowEnabled property to false to disable this behavior.
Dynamic overflow affects only the UI presentation of the commands, it doesn’t move commands from the PrimaryCommands collection to SecondaryCommands.
Version compatibility
The IsDynamicOverflowEnabled event 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.
Note
Dynamic overflow is available when your app is compiled for Windows 10, version 1607 and running on version 1607 (or later). Dynamic overflow is not available when your app is compiled for a previous version or is running on a previous version.
To avoid exceptions when your app runs on previous versions of Windows 10, do not connect this event without first performing a runtime check. This example shows how to use the ApiInformation class to check for the presence of this event before you use it.
<CommandBar x:Name="commandBar1" Loaded="CommandBar_Loaded">
...
</CommandBar>
private void CommandBar_Loaded(object sender, RoutedEventArgs e)
{
if (ApiInformation.IsEventPresent("Windows.UI.Xaml.Controls.CommandBar", "DynamicOverflowItemsChanging"))
{
commandBar1.DynamicOverflowItemsChanging += CommandBar1_DynamicOverflowItemsChanging;
}
}
- See Also