WinUI 3 Styling

Learn how to customize the appearance and feel of your WinUI 3 applications.

WinUI 3 provides a powerful and flexible styling system that allows you to create beautiful and consistent user experiences. This documentation covers the core concepts and techniques for styling your WinUI 3 applications, including XAML styles, resources, templates, and theme customization.

Core Concepts

XAML Styles

Styles are a fundamental mechanism for applying consistent formatting and behavior to UI elements. You can define a style in XAML and then apply it to one or more elements. This promotes reusability and maintainability of your UI code.

<!-- Define a style in your App.xaml or a specific resource dictionary -->
<Style TargetType="Button" x:Key="PrimaryButtonStyle">
    <Setter Property="Background" Value="{ThemeResource SystemAccentColor}"/>
    <Setter Property="Foreground" Value="White"/>
    <Setter Property="Padding" Value="12,6"/>
    <Setter Property="CornerRadius" Value="4"/>
</Style>

<!-- Apply the style to a button -->
<Button Content="Save" Style="{StaticResource PrimaryButtonStyle}"/>

Resources

Resources are objects that can be shared across multiple elements in your XAML. This includes styles, colors, brushes, templates, and more. Using resources allows you to define reusable assets and manage them centrally.

WinUI 3 heavily utilizes theme resources. These resources adapt their values based on the system's current light or dark theme, or accent color.

<!-- Example of using theme resources -->
<TextBlock Text="Welcome!"
           Foreground="{ThemeResource TextColorPrimary}"
           FontSize="24"/>

<Rectangle Width="100" Height="50" Fill="{ThemeResource SystemAccentColor}"/>

Control Templates

Control templates define the visual structure and appearance of a control. By modifying or replacing a control's template, you can completely change how it looks and behaves, while still retaining its underlying functionality.

<!-- Example: Customizing a Button template -->
<Style TargetType="Button">
    <Setter Property="Template">
        <Setter.Value>
            <ControlTemplate TargetType="Button">
                <Border Background="{TemplateBinding Background}"
                        CornerRadius="8"
                        Padding="{TemplateBinding Padding}">
                    <ContentPresenter HorizontalAlignment="Center" VerticalAlignment="Center"/>
                </Border>
            </ControlTemplate>
        </Setter.Value>
    </Setter>
</Style>

Styling Examples

Button Styling

Buttons can be styled using XAML styles and setters for properties like Background, Foreground, Padding, and CornerRadius. Theme resources like {ThemeResource SystemAccentColor} are commonly used.

Typography

This is a paragraph with default text styling. It uses the system's default font and color, adapting to the current theme.

This is a Heading 3

This is a highlighted paragraph.

You can customize fonts, sizes, weights, and colors using standard XAML properties. Consider using theme resources for text colors to ensure accessibility and theme consistency.

Layout Structures

Column 1

Column 2

Column 3

WinUI 3 offers various layout panels like Grid, StackPanel, and RelativePanel to arrange your UI elements effectively.

Theme Customization

WinUI 3 provides built-in support for system themes (Light and Dark). You can also define custom application themes or override existing theme resources to achieve a unique look and feel.

Key theme resources include:

{ThemeResource SystemAccentColor}: The user's chosen accent color.
{ThemeResource TextColorPrimary}, {ThemeResource TextColorSecondary}: Colors for primary and secondary text.
{ThemeResource BackgroundColor}, {ThemeResource SurfaceColor}: Background and surface colors.

To customize themes, you typically modify the ThemeDictionaries in your App.xaml or in separate resource dictionary files.

Further Resources

Microsoft Docs: XAML Styles

Microsoft Docs: XAML Resources

Microsoft Docs: WinUI Controls

WinUI 3 Docs