CommandBar

Overview

CommandBar is a surface that houses commands that operate on the content of the window, panel, or parent region it resides above. CommandBars are one of the most visible and recognizable ways to surface commands, and can be an intuitive method for interacting with content on the page; however, if overloaded or poorly organized, they can be difficult to use and hide valuable commands from your user. CommandBars can also display a search box for finding content, hold simple commands as well as menus, or display the status of ongoing actions.

Commands should be sorted in order of importance, from left-to-right or right-to-left depending on the culture. Secondarily, organize commands in logical groupings for easier recall. CommandBars work best when they display no more than 5-7 commands. This helps users quickly find your most valuable features. If you need to show more commands, consider using the overflow menu. If you need to render status or viewing controls, these go on the right side of the CommandBar (or left side if in a left-to-right experience). Do not display more than 2-3 items on the right side as it will make the overall CommandBar difficult to parse.

All command items should have an icon and a label. Commands can render as labels only as well. In smaller widths, commands can just use icon only, but only for the most recognizable and frequently used commands. All other commands should go into an overflow where text labels can be shown.

Usage

Basic CommandBar
<CommandBar Items=@items />
            
            
CommandBar with right items
<CommandBar Items=@items FarItems=@farItems OverflowItems=@overflowItems />
            
            
CommandBar with custom item rendering
<CommandBar Items=@customItems>
    <ItemTemplate>
        @if (context.ItemType == ContextualMenuItemType.Divider)
        {
            <CommandBarButton Disabled="true" IconName="GripperBarVertical" />
        }
        else
        {
            <CommandBarButton IconName=@context.IconName Text=@(!context.IconOnly ? context.Text : null)
              MenuItems=@context.Items
              Href=@context.Href
              OnClick=@(args => context.OnClick?.Invoke(new ItemClickedArgs() { MouseEventArgs = args, Key = context.Key }))
              Command=@context.Command CommandParameter=@context.CommandParameter
              Disabled=@context.Disabled AriaLabel=@context.AriaLabel Checked=@context.Checked ClassName=@context.ClassName
              Split=@context.Split Style=@context.Style />
        }
    </ItemTemplate>
</CommandBar>
            
            
Custom content in CommmandBarButton
<CommandBar Items=@contentItems>
    <ItemTemplate>
        <CommandBarButton IconName=@context.IconName Text=@(!context.IconOnly ? context.Text : null)
          MenuItems=@context.Items
          Href=@context.Href
          OnClick=@(args => context.OnClick?.Invoke(new ItemClickedArgs() { MouseEventArgs = args, Key = context.Key }))
          Command=@context.Command CommandParameter=@context.CommandParameter
          Disabled=@context.Disabled AriaLabel=@context.AriaLabel Checked=@context.Checked ClassName=@context.ClassName
          Split=@context.Split Style=@context.Style>
            @switch (context.Key)
            {
case "yellowCircle":
    <svg height="14" width="40">
        <ellipse cx="20" cy="8" rx="10" ry="5" style="fill:yellow;stroke:purple;stroke-width:2" />
        Sorry, your browser does not support inline SVG.
    </svg>
    break;
case "greenCircle":
    <svg height="14" width="40">
        <ellipse cx="20" cy="8" rx="10" ry="5" style="fill:green;stroke:purple;stroke-width:2" />
        Sorry, your browser does not support inline SVG.
    </svg>
    break;
            }
        </CommandBarButton>
    </ItemTemplate>
</CommandBar>
            
            
CommandBar with RadioButtons
<CommandBar Items=@itemsWithRadioButtons />