Quickstart: styling controls (HTML)

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

To customize the appearance of controls in your Windows Runtime app using JavaScript, you use Cascading Style Sheets (CSS), much like you would for a website. Windows apps using JavaScript also support some advanced control styling features, and the Windows Library for JavaScript provides a comprehensive set of styles that makes it easy to give your app the Windows 8 look and feel.

Here we show you how to include the WinJS style sheet, how to style HTML controls (also called intrinsic controls), how to style WinJS controls, and how to use the typography classes that WinJS provides.

See this feature in action as part of our App features, start to finish series: Windows Store app UI, start to finish

Prerequisites

• We assume that you know how to handle events in a Windows Runtime app using JavaScript. To learn the recommended way to handle events, see Quickstart: adding HTML controls and handling events.
• We assume that you can create and use WinJS controls. To learn how, see Quickstart: adding WinJS controls and styles.
• You must also be familiar with CSS. (For more info about CSS, see HTML/CSS/JavaScript Basics.)

Benefits of using the Windows Library for JavaScript style sheets

The WinJS style sheets provide:

• A set of styles that make your controls look great and work well with touch-based displays.
• Automatic support for high-contrast modes. Our styles were designed with high-contrast in mind, so when your app runs on a device in high-contrast mode, it will display properly.
• Automatic support for other languages. The WinJS style sheets automatically select the correct font for every language that Windows 8 supports. You can even use multiple languages in the same app and they'll be displayed properly.
• Automatic support for other reading orders. HTML and WinJS controls, layouts, and styles automatically adjust for languages that have a right-to-left reading direction.

Using the latest Windows Library for JavaScript style sheets

To enable the latest WinJS style sheets:

1. Download the latest version from Get WinJS and copy it to the directory for your app or website.
2. Add WinJS CSS and script references to each page of your app or website that uses WinJS features.

This example shows what these reference look like for an app that has its WinJS files in its root directory.

    <!-- WinJS style sheets (include one) -->
    <link href="/WinJS/css/ui-dark.css" rel="stylesheet">
    <link href="/WinJS/css/ui-light.css" rel="stylesheet">

    <!-- WinJS code -->
    <script src="/WinJS/js/WinJS.js"></script>

WinJS provides two default style sheets that you can use to give your app the Windows look and feel: ui-dark.css and ui-light.css.

• For apps that mostly display images or video, we recommend using the dark style sheet.
• For apps that contain a lot of text, we recommend using the light style sheet.

(If you're using a custom color scheme, use the style sheet that looks best with your app's look and feel.)

These style sheets define these styles:

• Base styles

  Styles for the html, body, and iframe elements.

• Intrinsic HTML control styles

  Styles for intrinsic HTML controls, such as button.

• Additional intrinsic HTML control classes

  CSS classes that you can assign to intrinsic HTML controls to give them a different look and feel. For a complete list of these classes, see CSS classes for HTML controls.

• WinJS control styles

  CSS classes that represent stylable parts of WinJS controls.

• Typography styles

  Styles for typographic elements, such as h1, dd, and p elements.

• Additional typography classes

  CSS classes that you can use to style your text. For example, you can use the win-type-large class to make an element's text large.

Customizing your app's look and feel

If you want to customize the look and feel from your app, you don't have throw out the WinJS styles and start over from scratch. It's easy to make incremental changes by overriding the styles you want to change.

In fact, it's better to override the WinJS styles rather than creating your own. When your app runs in high-contrast mode, any changes to the colors in the default styles are automatically overridden by a color scheme that supports high-contrast.

You can override any style in the default style sheet by creating your own style sheet and including it after the WinJS style sheet:

<!-- The WinJS style sheet. -->
<link href="/WinJS/css/ui-dark.css" rel="stylesheet">

<!-- Your style sheet for overriding portions of the default style sheet. -->
<link href="/css/mystylesheet.css" rel="stylesheet" />

How to specify colors

You can override the WinJS style sheets, or you can specify your own styles. When specifying your own styles, it's best to use the CSS system colors, because they automatically display correctly when your app is in high-contrast mode. For the list of system colors, see User-Defined System Colors.

If you don't use the User-Defined System Colors and instead specify an RGB value, that's ok too, as long as you're overriding an existing WinJS style. When you override a WinJS style and the system switches to high contrast mode, custom color information is ignored and a high-contrast mode compatible palette is used instead.

Styling HTML controls

You can style HTML controls (those controls that are part of the HTML5 standard, such as button, textarea, and select) just as you style them in a typical HTML page by using CSS. (To learn about CSS and how it works, see HTML/CSS/JavaScript Basics. )

For example, to style a text input box so that it's 400 pixels wide, you write this CSS:

input[type=text]
{
    width: 400px;
}

A typical control has several components, or sub-parts. For example, the text input control in the previous example has two parts: the text value and the clear button.

Windows apps using JavaScript provides CSS pseudo-elements that let you style the individual parts of many controls. The pseudo-element for the text input's value is -ms-value and the pseudo-element for the Clear button is -ms-clear.

To style a control part, use the syntax:

element selector::part name { /* Your styles here */ }

For example, to style the input box's Clear button, you create this style:

input[type=text]::-ms-clear
{
            border: 2px solid orange
}

You can combine pseudo-element selectors with other selectors so that you target a control with a specific class name or ID.

For example, to style the Clear button of a text input control that uses the "orangeButton" class , you create this style:

input[type=text].orangeButton::-ms-clear
{
            border: 2px solid orange
}

For more info about the different ways you can combine pseudo-elements and other selectors, see Understanding CSS selectors.

Here are the available parts for each HTML control.

Select control option elements also have CSS style support to give you fine-tuned control over the appearance of the dropdown items, such as color and font styles. This enables editing scenarios like a font picker control, where users can preview different font styles in a dropdown before choosing which font to use, like this.

<select id="fontNameSelect" onChange="formatText('fontName')">
    <option style="font-family:Arial;">Arial</option>
    <option style="font-family:Comic Sans MS;">Comic Sans MS</option>
    <option style="font-family:Courier New;">Courier New</option>
    <option style="font-family:Cursive;">Cursive</option>
    <option style="font-family:Segoe Script;">Segoe Script</option>
</select>

Using the HTML control classes

The style sheet includes CSS classes that you can assign to intrinsic HTML controls to give them a different look and feel. For example, you can use the win-backbutton class to make a standard button look like a button for navigating backwards.

<button class="win-backbutton"></button>

Using the class makes a button look like this:

Styling Windows Library for JavaScript controls

To style a WinJS control, you override the WinJS CSS classes for that control. For example, to style an AppBar, you override the win-appbar class.

The next example creates a style that hides the progress indicator of a ListView.

.win-listView .win-progress {
    display: none;
}

For a complete list of the available classes, see WinJS CSS classes. For more info about the classes that a specific control uses, see the reference page for that control.

Some controls, such as ListView and FlipView, also support item templates. Item templates give you a great amount of control over the appearance and content of list items. For more info, see Quickstart: adding a ListView and Quickstart: adding a FlipView.

Using the typography classes

The style sheet also contains CSS classes for typography that you can apply to any element that contains text. For example, you can use the win-title class to give a heading the Windows 8 title style. This example uses the typography classes to create different types of titles.

     <p class="win-type-xx-large">win-type-xx-large</p>
     <p class="win-type-medium">win-type-medium</p>
     <p class="win-type-xx-small">win-type-xx-small</p>

For a complete list of these typographic classes, see Typographic CSS classes.

Samples

To learn more about styling, check out these samples:

• App styling and branding sample

• CSS for high-contrast displays sample

Summary

You learned how to use the WinJS style sheets, how to style intrinsic and WinJS controls, and how to use the other CSS classes that WinJS provides for typography.

Related topics

HTML/CSS/JavaScript Basics

Understanding CSS Selectors

WinJS CSS classes

CSS classes for HTML controls

API Reference for Windows Runtime and Windows Library for JavaScript