Styling AppBars and ToolBars (HTML)

  • Article

[ 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 ]

Provides examples of how to style an AppBar or ToolBar and their controls.

Prerequisites

Introduction

Quickstart: Styling controls explains how the Windows Library for JavaScript style sheets provide a set of styles that automatically give your app the Windows 10 look and feel. The following examples demonstrate the use of Cascading Style Sheets (CSS) to customize some AppBar styles.

Light and dark themes

When you choose the light or the dark style sheet for your app, it affects the appearance of the AppBar as well as the other controls of your app. For this sample AppBar:

<div id="createAppBar" data-win-control="WinJS.UI.AppBar" data-win-options="{placement:'bottom'}">
        <button data-win-control="WinJS.UI.AppBarCommand" 
          data-win-options="{id:'cmdAdd',disabled:'true',label:'Add',icon:'add',tooltip:'Add item',section:'primary',type:'flyout',
          flyout:select('#addFlyout'),onclick:Sample.outputCommand}"></button>
        <button data-win-control="WinJS.UI.AppBarCommand" 
          data-win-options="{id:'cmdRemove',label:'Remove',icon:'remove',tooltip:'Remove item',section:'primary',
          onclick:Sample.outputCommand}"></button>
        <button data-win-control="WinJS.UI.AppBarCommand" 
          data-win-options="{id:'cmdEdit',label:'Edit',icon:'edit',tooltip:'Edit item',section:'primary',onclick:Sample.outputCommand}">
          </button>
        <button data-win-control="WinJS.UI.AppBarCommand" 
          data-win-options="{id:'cmdCamera',label:'Camera',icon:'camera',tooltip:'Take a picture',section:'primary',
          onclick:Sample.outputCommand}"></button>
        <button data-win-control="WinJS.UI.AppBarCommand" 
          data-win-options="{id:'cmdSettings',label:'Settings',icon:'settings',tooltip:'Settings',section:'primary',
          onclick:Sample.outputCommand}"></button>
        <button data-win-control="WinJS.UI.AppBarCommand" 
          data-win-options="{id:'cmdShare',label:'Share',icon:'reshare',tooltip:'Share',section:'primary',onclick:Sample.outputCommand}">
          </button>
        <button data-win-control="WinJS.UI.AppBarCommand" 
          data-win-options="{id:'cmdPrint',label:'Print',section:'secondary',onclick:Sample.outputCommand}"></button>
        <button data-win-control="WinJS.UI.AppBarCommand" 
          data-win-options="{id:'cmdNetwork',label:'Network',section:'secondary',onclick:Sample.outputCommand}"></button>
    </div>

To choose the dark style sheet:

<link href="//Microsoft.WinJS.2.0/css/ui-dark.css" rel="stylesheet">

Which produces an AppBar that looks like this:

Dark style app bar

Or to choose the light style sheet:

<link href="//Microsoft.WinJS.2.0/css/ui-light.css" rel="stylesheet">

Which produces an AppBar that looks like this:

Light style app bar

The ToolBar will have a similar appearance using the same style sheets.

Useful CSS properties

The following CSS properties are commonly used with the AppBar and ToolBar controls:

  • Border-color: Controls the border color of the AppBar.

    For example, border-color: rgb(255, 224, 100);

  • Background-color: Controls the background color of the AppBar.

    For example, background-color: rgb(255, 224, 100);

Note  These values are typically preset by ui-light.css or ui-dark.css.

 

Common part and state selectors

Some useful CSS selectors for styling parts and states of your control are:

  • .win-command styles the AppBar command label:

    .win-appbar .win-command
{
    color: rgb(28, 160, 218);
}

    Buttons with colored command labels

    Note  The user must touch or click on the elipses to open the AppBar and see this effect. Commands labels are hidden by default.

     

  • .win-commandimage styles the button's icon image:

    .win-appbar .win-commandimage
{
    color: rgb(28, 160, 218);
}

    Buttons with colored command icons

Pseudo-classes

You can use the following Pseudo_classes as selectors to style AppBar buttons when they're in certain states:

  • :hover - The user places the cursor over the button's icon and does not activate it by clicking, changing the button's background color until the cursor moves away from the button. A tooltip for the button is also displayed by default while hovering.

    Tooltip over the Home button while hovering

  • :active - The button is active between the time the user presses the control and chooses an option or if the button is set to type="toggle".

    Active Camera button

  • :disabled - The icon color change indicates that the button cannot accept user interaction. The disabled property of the button must be set to "disabled" for this pseudo-class to be applied.

    Disabled Home button

Styling an AppBar with custom colors

One more example of styling an AppBar:

.win-appbar .win-appbar-actionarea
{
   background-color: yellow;
}


.win-appbar .win-commandimage
{
    color: red;
}

produces the following AppBar colors:

Yellow app bar

To style the background color of the overflow area would look like this:

.win-appbar .win-appbar-overflowarea
{
   background-color: green;
}

And to style a ToolBar in the same way would look like this:

.win-toolbar win-toolbar-overflowarea{
   background-color: green;
}

.win-toolbar .win-commandimage
{
    color: red;
}

.win-toolbar win-toolbar-overflowarea
{
   background-color: green;
}

Styling to avoid

It is possible to use CSS to break the look and feel of AppBars and ToolBars. This is especially true for the smooth functioning of AppBar and ToolBar animation. Here are the known risk areas:

  • padding — Do not change from the defaults.

  • border — Do not change from the defaults.

  • margin — Style margins evenly, but only on ToolBar and AppBar elements:

    .win-toolbar, .win-appbar {
   margin: 3px;
}

  • background-color — Styling can be safely done on action areas and overflow areas:

    .win-toolbar-actionarea, .win-appbar-actionarea {
   background-color: rgb(0,0,127);
}
.win-toolbar-overflowarea, .win-appbar-overflowarea {
   background-color: rgb(0,0,255);

  • position,  float — Do not style these CSS attributes on the ToolBar element directly, but you can wrap ToolBar in a parent element that does style those rules. Note  This restriction does not apply to AppBar.

     

Known issues

  1. Hiding the ToolBar - The ToolBar component should only be hidden using public APIs. While it is common practice to use an "umbrella" CSS class to hide multiple components from view, this is not a good practice for ToolBar (or AppBar). The problem is that ToolBar has been performance optimized to cache the state of their commands, rather than to rely on the DOM to tell it whether or not a command is visible. This allows the ToolBar to be adaptive and overflow commands when they won’t fit in the available active area, while at the same time avoiding costly browser layouts that occur when you read from the DOM. Using CSS to Style buttons as hidden means that the ToolBar will not recognize that some command has been hidden and will start overflowing commands too early as the available space in the ToolBar's active area shrinks during window resizing.

    Instead, you should only set the Command.hidden property or call the ToolBar.showOnlyCommands() method to show and hide commands in the ToolBar.

  2. Adaptive overflow failure - ToolBar’s adaptive overflow behavior does not work well when the ToolBar element is made to “size to content”.

    For example, the ToolBar component is designed to exist inside other components (typically nested inside another div element). Normally, inside its own div, the ToolBar will take up 100% of its parent’s width. But, if the CSS layout used by the parent has it nested inside a few flex boxes and the parent's custom transportcontrols class is using align-items:center; to squish the ToolBar to only be the width of its commands, there will be unexpected behavior. This is because the ToolBar caches its width and tries to overflow commands when it thinks it doesn’t have sufficient room for them. ToolBar requires a constant element width, but the styles used in this scenario are giving it a flexible width.

    The work-around for this scenario (even combined with the solution for Hiding the ToolBar) involves changing the parent's custom transportcontrols class to use align-items:stretch;. Testing has shown this to be a simple solution, but if you cannot make the change to align-items for some reason, you can achieve the end result by putting align-self:stretch into the ToolBar element directly.

Summary and next steps

In this article we showed some examples of styling an AppBar and ToolBar and their controls. We also provided information about some design issues to keep in mind so you can avoid problems using AppBars and ToolBars in your application.

Learn more —hands on— about styling AppBars and ToolBars on the Try WinJS website. Play with the code and see the results immediately.

WinJS.UI.ToolBar

WinJS.UI.AppBar

WinJS.UI.AppBarCommand

AppBarIcon