.XAML File Format – Resources, styles and templates

Dictionaries and keys

<Window.Resources>
  <SolidColorBrush x:Key="Accent" Color="#FF2D6CDF"/>
  <Style TargetType="Button">                       <!-- the key is {x:Type Button} -->
    <Setter Property="Background" Value="{StaticResource Accent}"/>
  </Style>
  <DataTemplate DataType="{x:Type local:Person}">   <!-- the key is {x:Type local:Person} -->
    <TextBlock Text="{Binding Name}"/>
  </DataTemplate>
</Window.Resources>

• Where. The Resources property of any FrameworkElement (Window.Resources, Grid.Resources, Button.Resources), of Application (Application.Resources), of Style and of templates in some frameworks, or a file whose root is ResourceDictionary. Its children are the items; the explicit <ResourceDictionary> element is optional and is needed only to merge other dictionaries.
• Keys. Every item has a key: x:Key="name", or an implied one. A Style with a TargetType and no key has the type as its key, so it applies to every element of that type below the dictionary (an implicit style); a DataTemplate with a DataType and no key is chosen automatically for objects of that type. ControlTemplate has no implied key. UWP, WinUI and Silverlight accept an x:Name as a key. In Avalonia, ControlTheme is keyed by x:Key or its TargetType.
• Uniqueness. A key occurs once in a dictionary (implied keys included); a second one is an error when the dictionary is loaded. The same key may occur in different dictionaries, and the nearest one wins.
• Sharing. an item is made once and shared by every use, unless x:Shared="false". A Freezable (a brush) is frozen when it can be, which makes it cheap to share.
• Types. any object: brushes, colours, geometry, styles, templates, storyboards, converters, data providers, numbers and strings (<sys:Double x:Key="Pad">12</sys:Double> or <x:Double> in XAML 2009).

Lookup

A reference by {StaticResource Key} or {DynamicResource Key} looks in the element’s own dictionary, then in each ancestor’s, up to the root of the page, then in the application’s dictionary (Application.Resources), then in the theme dictionaries, then in the system resources (SystemColors, SystemFonts, SystemParameters). For an element made by a template, the template’s own dictionary and the templated parent come first. A StaticResource is resolved once, while the markup is read, so the item must come before the reference in the file when they are in the same dictionary; a DynamicResource is resolved at run time and again whenever the resource changes, and can refer forward. Only a dependency property can take a DynamicResource. UWP and WinUI add {ThemeResource}, which is looked up through the theme dictionaries (ResourceDictionary.ThemeDictionaries, keys Light, Dark, HighContrast) and again when the theme changes.

Merged dictionaries and addresses

<Application.Resources>
  <ResourceDictionary>
    <ResourceDictionary.MergedDictionaries>
      <ResourceDictionary Source="Styles/Buttons.xaml"/>
      <ResourceDictionary Source="pack://application:,,,/Theme;component/Colors.xaml"/>
    </ResourceDictionary.MergedDictionaries>
    <SolidColorBrush x:Key="Local" Color="Red"/>
  </ResourceDictionary>
</Application.Resources>

MergedDictionaries holds other dictionaries whose items are searched after the dictionary’s own items, in reverse order of listing (the last merged is searched first). Each merged dictionary is a separate dictionary, so keys may repeat between them. Source is a relative address (relative to the file that contains it), a pack://application:,,,/Assembly;component/path address (WPF), an ms-appx:///path address (UWP and WinUI), or an avares://Assembly/path address (Avalonia). Avalonia lists them in MergedDictionaries too, and adds Styles with StyleInclude Source="...". WPF’s theme dictionaries are found by ThemeInfoAttribute and the Themes/ file names listed on the file structure page.

Styles

A Style is a bundle of property values (and behaviour) applied to elements of one type.

Triggers (WPF)

Trigger actions are BeginStoryboard, PauseStoryboard, ResumeStoryboard, StopStoryboard, SeekStoryboard, SkipStoryboardToFill, RemoveStoryboard, SetStoryboardSpeedRatio and ControllableStoryboardAction; see animation. Avalonia has no triggers; its selectors and pseudo-classes (:pointerover, :pressed, :focus, :disabled, :checked) do the same. UWP and WinUI have StateTrigger, AdaptiveTrigger (MinWindowWidth, MinWindowHeight) and CompositeTrigger inside visual states; MAUI has Trigger, DataTrigger, MultiTrigger, EventTrigger and AdaptiveTrigger in Style.Triggers or Element.Triggers, and VisualStateManager.

Templates

The type of a framework template is the family FrameworkTemplate; the viewer treats any element whose name ends in Template as a template.

Visual states

VisualStateManager.VisualStateGroups (an attached property) holds VisualStateGroups, each with VisualStates that contain a Storyboard or Setters (UWP, WinUI, MAUI: VisualState.Setters) and optional VisualTransitions (WPF, Silverlight). The groups of a control are named in its documentation (CommonStates with Normal, MouseOver, Pressed, Disabled; FocusStates; ValidationStates) and a control looks for the parts and states its template defines. It is the main way to change a look in UWP, WinUI, Silverlight and MAUI, where there are no property triggers.

Name scopes

A name scope is the region in which an x:Name is unique and found by name. The root of the document is a scope; so is each template (ControlTemplate, DataTemplate and the others), because a template is applied many times and each application has its own names; so is a Style in WPF, where it lets triggers and storyboards name elements. A name may therefore repeat in different templates but not in one scope; the viewer’s Names tab shows each name with its scope. FindName, Storyboard.TargetName and ElementName bindings look names up in the scope. Dictionary items are not a scope of their own: the name of an element declared in Window.Resources is in the window’s scope.

Not described

Known, not yet covered

• Reference: the property lists of the Avalonia style system (selectors, classes, Transitions, Animations) and the MAUI trigger types are summarised, not complete.
• Reference: the part and state names of each WPF control’s template are not listed.

Unknown

• Reference: the lookup order was written from the documentation of WPF; the order in the other frameworks was not verified.