Plugin.Maui.Theme 9.2.1

🌈 Plugin.Maui.Theme

The Plugin.Maui.Theme library provides a powerful theme management service for .NET MAUI applications, allowing dynamic switching of visual styles.

🔧 Class ThemeService

A singleton service that manages application themes via ResourceDictionary.

📦 Properties and Fields

• ThemeService.Current: Static property to access the current instance.
• _themes: Dictionary containing registered themes (Dictionary<int, ResourceDictionary>).
• _appResources: Reference to the application's MergedDictionaries.
• _currentDict: Currently applied ResourceDictionary.
• _currentTheme: Key-value pair representing the active theme.

🔑 Метод InitAppResources

Initializes a reference to the application's MergedDictionaries.

public void InitAppResources(ResourceDictionary resource)

💥Throws ArgumentNullException if the resource is null.

🎨 Method AddTheme

Registers a theme in the collection.

AddTheme is deprecated. Please use AddThemes.

public void AddTheme(int key, ResourceDictionary theme, bool isDefault = false)

• key: Unique identifier for the theme.
• theme: ResourceDictionary defining the theme.
• isDefault: If true, sets the theme as the default.

🎨 Method AddThemes

The AddThemes method provides a convenient way to register multiple themes within the application without requiring explicit keys for each.

public IThemeService AddThemes(params ResourceDictionary[] resources)    or
public IThemeService AddThemes(params KeyValuePair<int, ResourceDictionary>[] resources)

This method is designed for scenarios where you have a collection of ResourceDictionary instances that you wish to register as themes, and you're comfortable with the system automatically assigning sequential keys to them, starting from the next available index.

Parameters

• resources: An array of ResourceDictionary objects that will be registered as themes.

Returns

• The current IThemeService instance. This allows for fluent chaining of method calls, enabling you to perform multiple theme-related operations in a concise manner (e.g., themeService.AddThemes(...).SetCurrentTheme(...)).

🔄 Method ChangeTheme

Switches the application to the specified theme.

public void ChangeTheme(int key)

🧯 Throws exceptions if the theme is not found or InitAppResources was not called.

⚙️ Method InitService

InitService is not recommended for use. Please use AddMethods.

Finalizes service setup.

public void InitService()

• If the theme is already in MergedDictionaries, it becomes active.
• Otherwise, the default or first available theme is applied.

📡 Event ThemeChanged

Triggered whenever the theme is changed:

public event EventHandler<ThemeChangedEventArgs>? ThemeChanged;

• Arguments include KeyTheme and NewTheme.

🧾 Record ThemeChangedEventArgs

public record ThemeChangedEventArgs(int KeyTheme, ResourceDictionary NewTheme);

Used to notify subscribers about theme changes.

What is a DynamicResource?

A DynamicResource is a reference to a resource that is resolved just before it's used. This means that if the value of the resource changes while the application is running, all elements using that DynamicResource will automatically update.

Unlike a StaticResource, which is resolved only once when the application starts, a DynamicResource provides flexibility and allows for a dynamic user interface.

How to Use a DynamicResource

Using a DynamicResource is very simple. You just need to specify the resource key in your XAML markup.

Behavior of Theme Addition

When using the AddThemes methods, it's important to understand how keys are assigned to the styles.

If you first call:

public IThemeService AddThemes(params KeyValuePair<int, ResourceDictionary>[] resources)

And then call:

public IThemeService AddThemes(params ResourceDictionary[] resources)

The key for the second set of resources will be calculated using the formula: maximum_key + 1, where maximum_key is the highest numerical key passed in the first call.

Example:

If your first call included themes with keys 1 and 5, the first resource in the second call will automatically be assigned the key 6.

✅ Usage Example

In the App.xaml.cs class, you can use ThemeService like this:

		public static MauiApp CreateMauiApp()
		{
			var builder = MauiApp.CreateBuilder();
			builder
				.UseMauiApp<App>()
				.ConfigureFonts();
				// Your theme service initialization
				 // This line assumes 'UseTheme()' is an extension method
				  // on MauiAppBuilder or configures a theme service.
				   builder.UseTheme(); // <-- Call your UseTheme() method here

			return builder.Build();
		}

public App(IThemeService themeService)
{
	InitializeComponent();

	themeService.InitAppResources(Resources)
				.AddThemes(new KeyValuePair<int, ResourceDictionary>(99, new RedTheme()))
				.AddThemes(new BlueTheme(), new DarkTheme());

	themeService.ThemeChanged += Current_ThemeChanged;

}

🧠 Highlights

• Supports multiple themes.
• Enables dynamic switching.
• Event-driven UI updates.

🛠 Author: Fishman 📅 Last updated: July 2025

Acknowledgments

We're thrilled to announce that the preparation of version 9.2.0 was significantly supported by Алексом Добрыниным. His contributions were invaluable in bringing this release to fruition.

📄 License

This project is licensed under the Boost Software License – Version 1.0 – August 17th, 2003.