Quickstart: Styling controls (XAML)

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

The XAML framework offers many ways to customize the appearance of your apps. Styles enable you to set control properties and reuse those settings for a consistent appearance across multiple controls.

Roadmap: How does this topic relate to others? See:

This topic contains the following sections:

  • Prerequisites
  • Style basics
  • Applying an implicit or explicit style
  • Using based-on styles
  • Use tools to work with styles easily
  • Modifying the Windows Runtime default styles
  • The Template property
  • Related topics

Prerequisites

We assume that you can add controls to your UI, set their properties, and attach event handlers. For instructions for adding controls to your app, see Quickstart: Adding controls and handing events.

Style basics

Use styles to extract visual property settings into reusable resources. Here's an example that shows 3 buttons with a style that sets the BorderBrush, BorderThickness and Foreground properties. By applying a style, you don't have to set these properties on each control separately, and the controls all have the same appearance.

You can define a style inline in the Extensible Application Markup Language (XAML) for a control, or as a reusable resource. Define resources in an individual page's XAML file, in the App.xaml file, or in a separate resource dictionary XAML file. A resource dictionary XAML file can be shared across apps, and more than one resource dictionary can be merged in a single app. Where the resource is defined determines the scope in which it can be used. Page-level resources are available only in the page where they are defined. If resources with the same key are defined in both App.xaml and in a page, the resource in the page overrides the resource in App.xaml. If a resource is defined in a separate resource dictionary file, it's scope is determined by where the resource dictionary is referenced.

In the Style definition, you need a TargetType attribute and a collection of one or more Setter elements. The TargetType attribute is a string that specifies a FrameworkElement type to apply the style to. The TargetType value must specify a FrameworkElement-derived type that's defined by the Windows Runtime or a custom type that's available in a referenced assembly. If you try to apply a style to a control and the control's type doesn't match the TargetType attribute of the style you're trying to apply, an exception occurs.

Each Setter element requires a Property and a Value. These property settings indicate what control property the setting applies to, and the value to set for that property. You can set the Setter.Value with either attribute or property element syntax. The XAML here shows the style we used in the previous example. In this XAML, the first two Setter elements use attribute syntax, but the last Setter, for the BorderBrush property, uses property element syntax. The example doesn't use the x:Key attribute, so the style is implicitly applied to the buttons. Applying styles implicitly or explicitly is explained in the next section.

<Page.Resources>
    <Style TargetType="Button">
        <Setter Property="BorderThickness" Value="5" />
        <Setter Property="Foreground" Value="Blue" />
        <Setter Property="BorderBrush" >
            <Setter.Value>
                <LinearGradientBrush StartPoint="0.5,0" EndPoint="0.5,1">
                    <GradientStop Color="Yellow" Offset="0.0" />
                    <GradientStop Color="Red" Offset="0.25" />
                    <GradientStop Color="Blue" Offset="0.75" />
                    <GradientStop Color="LimeGreen" Offset="1.0" />
                </LinearGradientBrush>
            </Setter.Value>
            </Setter>
        </Style>
</Page.Resources>

Applying an implicit or explicit style

If you define a style as a resource, there are two ways to apply it to your controls:

If a style contains the x:Key attribute, you can only apply it to a control by setting the Style property of the control to the keyed style. In contrast, a style without an x:Key attribute is automatically applied to every control of its target type, that doesn't otherwise have an explicit style setting.

Here are two buttons that demonstrate implicit and explicit styles.

In this example, the first style has an x:Key attribute and its target type is Button. The first button's Style property is set to this key, so this style is applied explicitly. The second style is applied implicitly to the second button because its target type is Button and the style doesn't have an x:Key attribute.

<Page.Resources>
    <Style x:Key="PurpleStyle" TargetType="Button">
        <Setter Property="FontFamily" Value="Lucida Sans Unicode" />
        <Setter Property="FontStyle" Value="Italic" />
        <Setter Property="FontSize" Value="14" />
        <Setter Property="Foreground" Value="MediumOrchid" />
    </Style>

    <Style TargetType="Button">
        <Setter Property="FontFamily" Value="Lucida Sans Unicode" />
        <Setter Property="FontStyle" Value="Italic" />
        <Setter Property="FontSize" Value="14" />
        <Setter Property="RenderTransform">
            <Setter.Value>
                <RotateTransform Angle="25" />
            </Setter.Value>
        </Setter>
        <Setter Property="BorderBrush" Value="Orange" />
        <Setter Property="BorderThickness" Value="2" />
        <Setter Property="Foreground" Value="Orange" />
    </Style>
</Page.Resources>
<Grid x:Name="LayoutRoot">
    <Button Content="Button" Height="23" Width="75" Style="{StaticResource PurpleStyle}" />
    <Button Content="Button" Height="23" Width="75" />
</Grid>

Using based-on styles

To make styles easier to maintain and to optimize style reuse, you can create styles that inherit from other styles. You use the BasedOn property to create inherited styles. Styles that inherit from other styles must target the same type of control or a control that derives from the type targeted by the base style. For example, if a base style targets ContentControl, styles that are based on this style can target ContentControl or types that derive from ContentControl such as Button and ScrollViewer. If a value is not set in the based-on style, it's inherited from the base style. To change a value from the base style, the based-on style overrides that value. The next example shows a Button and a CheckBox with styles that inherit from the same base style.

The base style targets ContentControl, and sets the Height, and Width properties. The styles based on this style target CheckBox and Button, which derive from ContentControl. The based-on styles set different colors for the BorderBrush and Foreground properties.

<Page.Resources>
    <Style x:Key="BasicStyle" TargetType="ContentControl">
        <Setter Property="Width" Value="100" />
        <Setter Property="Height" Value="30" />
    </Style>
    <Style x:Key="ButtonStyle" TargetType="Button" BasedOn="{StaticResource BasicStyle}">
        <Setter Property="BorderBrush" Value="Orange" />
        <Setter Property="BorderThickness" Value="2" />
        <Setter Property="Foreground" Value="Orange" />
    </Style>
    <Style x:Key="CheckBoxStyle" TargetType="CheckBox" BasedOn="{StaticResource BasicStyle}">
        <Setter Property="BorderBrush" Value="Green" />
        <Setter Property="BorderThickness" Value="2" />
        <Setter Property="Foreground" Value="Green" />
    </Style>
</Page.Resources>

<Grid Background="White">
    <Button Content="Button" Style="{StaticResource ButtonStyle}"/>
    <CheckBox Content="CheckBox"  Style="{StaticResource CheckBoxStyle}"/>
</Grid>

Use tools to work with styles easily

A fast way to apply styles to your controls is to right-click on a control on the Microsoft Visual Studio XAML design surface and select Edit Style or Edit Template (depending on the control you are right-clicking on). You can then apply an existing style by selecting Apply Resource or define a new style by selecting Create Empty. If you create an empty style, you are given the option to define it in the page, in the App.xaml file, or in a separate resource dictionary.

Modifying the Windows Runtime default styles

You should use the styles that come from the Windows Runtime default XAML resources when you can. When you have to define your own styles, try to base your styles on the default ones when possible (using based-on styles as explained earlier, or start by editing a copy of the original default style).

The Template property

A style setter can be used for the Template property of a Control, and in fact this makes up the majority of a typical XAML style and an app's XAML resources. This is discussed in more detail in the topic Quickstart: Control templates.

Roadmap for creating apps using C#, C++, or VB

Adding controls and content

Quickstart: Control templates

ResourceDictionary and XAML resource references

Style

Setter

x:Key attribute