Command​Bar Command​Bar Command​Bar 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
<CommandBar .../>
-or-
<CommandBar>
  commandBarElements
</CommandBar>
Inheritance
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Inherited Members

Inherited properties

Inherited events

Inherited methods

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.

A compact command bar Here's the same CommandBar shown in its open state. The labels show the main parts of the control.

Parts of a command bar 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&#x00AD;longlabel"/>

When the label wraps at the hinted location, it looks like this.

A minimal command bar

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.

A minimal command bar 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&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 CommandBar control.

Resource keyDescription
CommandBarBackgroundBackground color at rest
CommandBarForegroundText color at rest
CommandBarHighContrastBorderBorder color for high-contrast
CommandBarEllipsisIconForegroundDisabledColor of ellipsis icon when disabled
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 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>

Constructors

CommandBar() CommandBar() CommandBar()

Properties

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
<CommandBar CommandBarOverflowPresenterStyle={StaticResource styleResourceKey}/>

Value
Style Style Style

The applied Style for the overflow content of the CommandBar, if present; otherwise, null. The default is null.

Attributes

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.

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
Attributes

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
Value
CommandBarTemplateSettings CommandBarTemplateSettings CommandBarTemplateSettings

An object that provides calculated values for templates.

Attributes

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
<CommandBar DefaultLabelPosition="commandBarDefaultLabelPositionMemberName" />
Value
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.

Attributes
Additional features and requirements
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

Identifies the DefaultLabelPosition dependency property.

public static DependencyProperty DefaultLabelPositionProperty { get; }public static DependencyProperty DefaultLabelPositionProperty { get; }Public Static ReadOnly Property DefaultLabelPositionProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the DefaultLabelPosition dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

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
<CommandBar IsDynamicOverflowEnabled="bool"/>
Value
bool bool bool

true if primary commands automatically move to the overflow menu when space is limited; otherwise, false. The default is true.

Attributes
Additional features and requirements
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

Identifies the IsDynamicOverflowEnabled dependency property.

public static DependencyProperty IsDynamicOverflowEnabledProperty { get; }public static DependencyProperty IsDynamicOverflowEnabledProperty { get; }Public Static ReadOnly Property IsDynamicOverflowEnabledProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the IsDynamicOverflowEnabled dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

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
<CommandBar OverflowButtonVisibility="commandBarOverflowButtonVisibilityMemberName" />
Value
CommandBarOverflowButtonVisibility CommandBarOverflowButtonVisibility CommandBarOverflowButtonVisibility

An enumeration value that indicates when a command bar's overflow button is shown. The default is Auto.

Attributes
Additional features and requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

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
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the OverflowButtonVisibility dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

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>
<CommandBar>
    <CommandBar.PrimaryCommands>
      commandBarElements
    </CommandBar.PrimaryCommands>
</CommandBar>
Value

The collection of primary command elements for the CommandBar. The default is an empty collection.

Attributes

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.

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
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the PrimaryCommands dependency property.

Attributes

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>
<CommandBar>
    <CommandBar.SecondaryCommands>
       commandBarElements
    </CommandBar.SecondaryCommands>
</CommandBar>
Value

The collection of secondary command elements for the CommandBar. The default is an empty collection.

Attributes

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.

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
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the SecondaryCommands dependency property.

Attributes

Events

DynamicOverflowItemsChanging DynamicOverflowItemsChanging DynamicOverflowItemsChanging

Occurs when items move into or out of the overflow menu.

public event TypedEventHandler DynamicOverflowItemsChangingpublic event TypedEventHandler DynamicOverflowItemsChangingPublic Event DynamicOverflowItemsChanging
<CommandBar DynamicOverflowItemsChanging="eventhandler"/>
Attributes
Additional features and requirements
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

See Also