Merged Dictionaries In Xamarin.Forms

Placing styles and other resources in your ResourceDictionary is a great way to reuse these elements through your page or application. However, up until now, you could only merge with one external resource dictionary, using MergedWith. With MergedDictionaries, you can now separate out your styles into multiple files, and merge them as desired on each page.

Note: I personally wrote this feature in Xamarin.Forms. My PR 1138 has been merged, with many thanks to Stephane for the code review. This is now available in Xamarin.Forms 2.5.0 and above.

How To Use

Create a new XAML file, and create your resource dictionary, as below.  I called the my new file, MyResourceDictionary.

<?xml version="1.0" encoding="utf-8" ?>
<ResourceDictionary xmlns="http://xamarin.com/schemas/2014/forms"
                   xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
                   x:Class="Mobile.Style.MyResourceDictionary"> 
    <Style TargetType="Button"> 
        <Setter Property="TextColor" Value="White" /> 
    </Style>
</ResourceDictionary>

Then, in your ContentPage, do the following.

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:theme="clr-namespace:Mobile.Style"
             x:Class="Mobile.MainPage">
    <ContentPage.Resources>
        <ResourceDictionary.MergedDictionaries>
            <theme:MyResourceDictionary />
            <!-- Add as many as you want here -->
        </ResourceDictionary.MergedDictionaries>
    </ContentPage.Resources>
</ContentPage>

Or, you can even do this, if you want to get creative, but I recommend the first approach.

<ContentPage.Resources>
    <ResourceDictionary.MergedDictionaries>
        <ResourceDictionary MergedWith="theme:MyResourceDictionary">
            <Style TargetType="Button"> 
                <Setter Property="TextColor" Value="White" /> 
            </Style>
        </ResourceDictionary>
    </ResourceDictionary.MergedDictionaries>
</ContentPage.Resources>

Searching

A ResourceDictionary, could have the same key as a dictionary that is merged via MergedWith or MergedDictionaries. When the page is trying to find a key, it uses this search method.

  1. Check in page’s local keys
  2. Check MergedWith ResourceDictionary
  3. Check each MergedDictionaries, in the order they are listed

The first place it finds the key, it uses that key. Hence the priority is set based on the list above.

Performance Considerations

Searching resource dictionaries, involves checking every key, until it finds something suitable. If you have a large amount of keys, and the key you are looking for is right at the end, and you use this key multiple times, it may impact performance. It is best to ensure you only place the appropriate resource dictionaries in your page, to avoid unnecessary searching.

Why MergedWith and not Source

UWP and WPF use Source as their property name, not MergedWith. Currently, the resource dictionary has the MergedWith tag to merge one Resource Dictionary, with another. It is planned that the Source attribute will be used in the future, but will also support finding dictionaries based on URI as well. Once this occurs, it is expected that MergedWith, will be deprecated.


XAMARIN.FORMS MONTHLY NEWSLETTER

JOIN 1,200+ SUBSCRIBERS

  1. Don't miss out on updates
  2. The latest info from this site, Xamarin and the community
  3. Unsubscribe at any time*

* We use MailChimp, with double opt-in, and instant unsubscribe

Microsoft MVP | Xamarin MVP | Xamarin Certified Developer |
Exrin MVVM Framework | Xamarin Forms Developer | Melbourne, Australia

Related Posts

Tagged:Tags:

7 Comments

  1. Brian

    This is awesome, thanks Adam! Merged resource dictionaries is something I’ve missed coming from WPF and SL background

  2. Adam A

    In the searching section where the the application’s ResourceDictionary fit in? Is it the following?

    Check in page’s local keys
    Check MergedWith ResourceDictionary
    *Check in application’s ResourceDictionary*
    Check each MergedDictionaries, in the order they are listed

    1. Adam Pedley

      Thats the final step after all of these have been searched. It’s not really part of the ResourceDictionary, it’s just that the Markup Extensions, move to the Application Resource Dictionary, after it has checked out all of these.

      1. Adam A

        So a complete list would be the following?
        Direct element styling
        Page ResourceDictionary
        Page MergedWith ResourceDictionary
        Page MergedDictionaries, in the order they are listed
        Application ResourceDictionary
        Application MergedWith ResourceDictionary
        Application MergedDictionaries, in the order they are list