Skip to main content

​
Resources

Avalonia’s resource system provides a way to define and reuse objects throughout your application. Resources are typically colors, brushes, styles, templates, and other reusable objects.

​
ResourceDictionary

The ResourceDictionary class is an indexed dictionary for storing and retrieving resources.

​
Namespace

Avalonia.Controls

​
Inheritance

Object → ResourceProvider → ResourceDictionary
Implements: IResourceDictionary, IThemeVariantProvider

​
Constructors

​
ResourceDictionary()
constructor
Creates a new instance of the ResourceDictionary class.
​
ResourceDictionary(IResourceHost owner)
constructor
Creates a new instance with the specified owner.Parameters:
  • owner (IResourceHost): The resource host that owns this dictionary

​
Properties

​
Count
int
Gets the number of resources in the dictionary.
​
this[object key]
object
Gets or sets the resource with the specified key.
​
Keys
ICollection<object>
Gets a collection containing the keys in the resource dictionary.
​
Values
ICollection<object?>
Gets a collection containing the values in the resource dictionary.
​
MergedDictionaries
IList<IResourceProvider>
Gets a list of merged resource dictionaries.Merged dictionaries are searched when looking up resources.
​
ThemeDictionaries
IDictionary<ThemeVariant, IThemeVariantProvider>
Gets the theme-specific resource dictionaries.Allows defining different resources for light, dark, and custom themes.

​
Methods

​
Add
void
Adds a resource to the dictionary.Parameters:
  • key (object): The resource key
  • value (object): The resource value
​
Remove
bool
Removes a resource from the dictionary.Parameters:
  • key (object): The resource key
Returns: true if the resource was removed
​
TryGetValue
bool
Tries to get a resource value.Parameters:
  • key (object): The resource key
  • value (out object): The resource value if found
Returns: true if the resource was found

​
Usage in XAML

​
Defining Resources

<Window xmlns="https://github.com/avaloniaui"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <Window.Resources>
        <!-- Simple values -->
        <x:Double x:Key="StandardSpacing">8</x:Double>
        <x:Double x:Key="LargeSpacing">16</x:Double>
        
        <!-- Colors -->
        <Color x:Key="PrimaryColor">#4A90E2</Color>
        <Color x:Key="SecondaryColor">#7B68EE</Color>
        
        <!-- Brushes -->
        <SolidColorBrush x:Key="PrimaryBrush" Color="{StaticResource PrimaryColor}" />
        <LinearGradientBrush x:Key="GradientBrush" StartPoint="0%,0%" EndPoint="100%,100%">
            <GradientStop Color="#4A90E2" Offset="0" />
            <GradientStop Color="#7B68EE" Offset="1" />
        </LinearGradientBrush>
        
        <!-- Styles -->
        <Style x:Key="HeaderTextStyle" Selector="TextBlock">
            <Setter Property="FontSize" Value="20" />
            <Setter Property="FontWeight" Value="Bold" />
        </Style>
    </Window.Resources>
    
    <StackPanel>
        <TextBlock Text="Header" 
                   Foreground="{StaticResource PrimaryBrush}"
                   Styles="{StaticResource HeaderTextStyle}" />
    </StackPanel>
</Window>

​
Using Resources

​
StaticResource

Resolves once at initialization: 
<Button Background="{StaticResource PrimaryBrush}" />

​
DynamicResource

Resolves when accessed and updates when resource changes: 
<Button Background="{DynamicResource PrimaryBrush}" />
Use DynamicResource for theme-aware resources that might change at runtime (e.g., when switching between light/dark themes).

​
Merged Dictionaries

<Window.Resources>
    <ResourceDictionary>
        <ResourceDictionary.MergedDictionaries>
            <ResourceInclude Source="/Resources/Colors.axaml" />
            <ResourceInclude Source="/Resources/Brushes.axaml" />
            <ResourceInclude Source="/Resources/Styles.axaml" />
        </ResourceDictionary.MergedDictionaries>
        
        <!-- Additional resources -->
        <SolidColorBrush x:Key="LocalBrush" Color="Red" />
    </ResourceDictionary>
</Window.Resources>

​
Theme Dictionaries

<Application.Resources>
    <ResourceDictionary>
        <ResourceDictionary.ThemeDictionaries>
            <!-- Light theme resources -->
            <ResourceDictionary x:Key="Light">
                <SolidColorBrush x:Key="BackgroundBrush" Color="White" />
                <SolidColorBrush x:Key="ForegroundBrush" Color="Black" />
            </ResourceDictionary>
            
            <!-- Dark theme resources -->
            <ResourceDictionary x:Key="Dark">
                <SolidColorBrush x:Key="BackgroundBrush" Color="#1E1E1E" />
                <SolidColorBrush x:Key="ForegroundBrush" Color="White" />
            </ResourceDictionary>
        </ResourceDictionary.ThemeDictionaries>
    </ResourceDictionary>
</Application.Resources>

<Window Background="{DynamicResource BackgroundBrush}"
        Foreground="{DynamicResource ForegroundBrush}">
    <!-- Content -->
</Window>

​
Code-Behind Usage

​
Accessing Resources

using Avalonia;
using Avalonia.Controls;
using Avalonia.Media;

// Find resource in window resources
if (window.Resources.TryGetValue("PrimaryBrush", out var resource))
{
    if (resource is IBrush brush)
    {
        button.Background = brush;
    }
}

// Find resource in application resources
if (Application.Current?.Resources.TryGetValue("PrimaryColor", out var colorRes) == true)
{
    if (colorRes is Color color)
    {
        // Use the color
    }
}

​
Adding Resources Programmatically

// Add to window resources
window.Resources.Add("DynamicBrush", new SolidColorBrush(Colors.Blue));

// Add to application resources
Application.Current.Resources.Add("GlobalFont", new FontFamily("Arial"));

// Remove a resource
window.Resources.Remove("OldResource");

​
Creating a Resource Dictionary

var resourceDict = new ResourceDictionary
{
    { "Spacing", 8.0 },
    { "LargeSpacing", 16.0 },
    { "PrimaryColor", Colors.Blue },
    { "PrimaryBrush", new SolidColorBrush(Colors.Blue) }
};

// Add to window
window.Resources.MergedDictionaries.Add(resourceDict);

​
Theme-Aware Resource Lookup

using Avalonia.Styling;

if (Application.Current.TryGetResource(
    "AccentColor", 
    ThemeVariant.Dark, 
    out var accentColor))
{
    // Use accent color for dark theme
}

​
Resource Files

Create separate XAML files for reusable resources: Colors.axaml: 
<ResourceDictionary xmlns="https://github.com/avaloniaui"
                    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <Color x:Key="Primary">#4A90E2</Color>
    <Color x:Key="Secondary">#7B68EE</Color>
    <Color x:Key="Success">#10B981</Color>
    <Color x:Key="Warning">#F59E0B</Color>
    <Color x:Key="Error">#EF4444</Color>
</ResourceDictionary>
Brushes.axaml: 
<ResourceDictionary xmlns="https://github.com/avaloniaui"
                    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <ResourceDictionary.MergedDictionaries>
        <ResourceInclude Source="/Resources/Colors.axaml" />
    </ResourceDictionary.MergedDictionaries>
    
    <SolidColorBrush x:Key="PrimaryBrush" Color="{StaticResource Primary}" />
    <SolidColorBrush x:Key="SecondaryBrush" Color="{StaticResource Secondary}" />
</ResourceDictionary>

​
Best Practices

Split resources by type (colors, brushes, styles) for better maintainability.
/Resources/
  Colors.axaml
  Brushes.axaml
  Styles.axaml
  Templates.axaml
Use descriptive names that indicate purpose, not appearance.
<!-- Good -->
<Color x:Key="PrimaryColor">#4A90E2</Color>
<Color x:Key="ErrorColor">#EF4444</Color>

<!-- Bad -->
<Color x:Key="BlueColor">#4A90E2</Color>
<Color x:Key="RedColor">#EF4444</Color>
Resources that change based on theme should use DynamicResource.
<Button Background="{DynamicResource ButtonBackground}" />
  • Application-wide: Application.Resources
  • Window-specific: Window.Resources
  • Control-specific: Control.Resources

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us