Using Avalonia Theme Colors and Brushes for Custom UI

In Avalonia, reference active theme colors and brushes like foreground, background, or accent using DynamicResource in XAML for automatic theme switching—keys such as ThemeForegroundBrush (Simple theme) or BrushTextControlForeground (Fluent) pull from the current variant. Programmatically, grab them via Application.Current.TryGetResource(key, ActualThemeVariant) to match the OS or app theme without hardcoding. This keeps custom visuals like separators or rulers in sync across light/dark modes in Avalonia themes.

Contents

• Understanding Avalonia Theme Resources
• Referencing Theme Brushes in XAML
• Retrieving Theme Colors in Code
• Canonical Resource Keys for Built-in Themes
• ColorPaletteResources and Palettes Explained
• Best Practices for Custom UI Elements

Sources

1. How To Use Theme Variants | Avalonia Docs
2. Fluent Theme | Avalonia Docs
3. ColorPaletteResources Class | Avalonia API-Reference
4. How to get the accent color for the current theme? · AvaloniaUI/Avalonia · Discussion #13968
5. ColorPaletteResources.Properties.cs - Avalonia.Themes.Fluent (GitHub)
6. BaseResources.xaml - Avalonia.Themes.Fluent (GitHub)
7. FluentControlResources.xaml - Avalonia.Themes.Fluent (GitHub)

Conclusion

Stick to DynamicResource for XAML and TryGetResource in code to keep your custom Avalonia UI elements theme-aware—it’s the cleanest path without reinventing palettes. Dive into the Fluent or Simple theme source files on GitHub for exact keys, and always test light/dark switches. You’ll end up with visuals that feel native, no matter the user’s setup.

Understanding Avalonia Theme Resources

Avalonia’s themes, like Fluent or Simple, don’t hand you a neat “semantic colors” list in the docs. Instead, they pack brushes into ThemeDictionaries keyed to variants (light/dark). Why? So controls and custom bits update automatically when the theme flips—say, from Windows light to dark.

The ActualThemeVariant property on your app, window, or control tells you what’s active right now. Resources in these dictionaries only load via DynamicResource; try StaticResource and you’ll hit a runtime error unless the key exists outside theme scopes. Frustrating at first, but it forces theme fidelity.

Take ProgressBar in the Simple theme: it grabs ThemeForegroundBrush and ThemeAccentBrush. Where do those live? Scattered in theme XAML files, but more on that soon.

Referencing Theme Brushes in XAML

Want a separator line that matches the theme’s subtle background divider? Slap DynamicResource on it. Here’s a quick custom ruler that picks the right stroke:

<Line StrokeThickness="1" Stroke="{DynamicResource ThemeBorderMidBrush}">
 <!-- Or for Fluent: Stroke="{DynamicResource BrushDividerStroke}" -->
</Line>

This pulls from the active theme’s dictionary. Switch to dark mode? It updates without a rebuild. But you need the right key—ThemeBorderMidBrush works in Simple; Fluent leans granular like BrushDividerStroke or BrushControlBorderLow.

For a full custom visual, wrap in a UserControl or draw in Canvas. Bind to ActualThemeVariant if you want logic:

<Canvas x:Name="Ruler">
 <Canvas.Stroke="{DynamicResource ThemeForegroundBrush}"/>
 <!-- Ticks with theme accent -->
 <Rectangle Fill="{DynamicResource ThemeAccentBrush}" Width="2" Height="10"/>
</Canvas>

Pro tip: Scope overrides with RequestedThemeVariant="Dark" on a parent, but inherit globally for consistency.

Retrieving Theme Colors in Code

No XAML? Or need brushes for Skia drawing? Avalonia’s got your back with a runtime API akin to WPF’s SystemBrushes, but theme-aware.

Hit up Application.Current.TryGetResource(key, Application.Current.ActualThemeVariant, out var brush). Pass the theme variant, and it fishes from the right dictionary. Example for a custom separator in C#:

var themeVariant = Application.Current.ActualThemeVariant ?? ThemeVariant.Light;
if (Application.Current.TryGetResource("ThemeBorderLowBrush", themeVariant, out var strokeBrush))
{
 // Use (ISolidColorBrush)strokeBrush for your drawing context
 drawingContext.DrawLine(strokeBrush, startPoint, endPoint);
}

Nail the accent? Same deal: "AccentBrushForeground" or check this GitHub discussion for OS color via PlatformSettings.GetColorValues(). It’s not SystemColors, but close—and variant-specific.

Fallbacks matter: if the key flops, default to ThemeBrush or a solid color. Cache the brush? Sure, but rebinding on theme change keeps it fresh.

Canonical Resource Keys for Built-in Themes

No master list in docs, right? Dig into source. Simple theme keeps it high-level: ThemeForegroundBrush, ThemeBackgroundBrush, ThemeAccentBrush, ThemeBorderLowBrush, ThemeBorderMidBrush.

Fluent? Granular city. From BaseResources.xaml and FluentControlResources.xaml:

• Foreground-ish: BrushTextControlForeground, BrushForeground
• Backgrounds: BrushBackground, BrushCardBackground
• Accents: AccentBrushPrimary, BrushAccent
• Separators/Dividers: BrushDividerStroke, ThemeBorderLowBrush
• Errors: BrushCriticalFill, BrushCriticalForeground

Full palette feeds these via ColorPaletteResources—props like Accent, BaseLow, RegionColor. Inspect the repo; keys aren’t “semantic” like Material.Avalonia’s, but consistent within a theme.

Simple for basics, Fluent for polish. Mix? Tricky—stick to one.

ColorPaletteResources and Palettes Explained

ColorPaletteResources isn’t for direct use; it’s Fluent’s palette engine. Define overrides like:

<FluentTheme>
 <FluentTheme.Palettes>
 <ColorPaletteResources x:Key="Light" Accent="#Green" BaseLow="#White"/>
 </FluentTheme.Palettes>
</FluentTheme>

This tweaks base colors (Accent, AltHigh, ChromeLow—you name it, API docs list them). Theme brushes derive from these statically at startup (except Accent, which binds runtime).

Use palettes to customize the whole theme, not pluck singles. For consuming? Reference derived brushes as above. BaseColorPalette.xaml? Internal to Fluent, generating from palettes.

When? Override for branding; otherwise, use provided brushes.

Best Practices for Custom UI Elements

Build theme-respecting customs like this:

1. XAML first: DynamicResource everywhere. Test variant switches.
2. Code fallback: TryGetResource with ActualThemeVariant. Listen to ActualThemeVariantChanged.
3. Custom controls: Expose DirectProperty for brushes, default to theme lookups.
4. Performance: Avoid per-frame lookups; subscribe to theme events.
5. Discovery: Repo dive or theme.xaml.live editor for previews.
6. Cross-theme: If Fluent/Simple toggleable, conditional keys or shared semantics like “Foreground”.

Custom ruler example? Line Stroke="{DynamicResource BrushDividerStroke}"—boom, native feel. Users flip themes? Yours adapts. Skip hardcodes; embrace the dictionaries.

Had the same head-scratcher? Source inspection unlocks it. Your app will shine across platforms.