Announcing Calcite .NET Toolkit

dotMorten_esri · ‎03-10-2025

On the ArcGIS Maps SDK for .NET Team, we often need to build samples and demos that not only showcase API features but also look good. We wanted a simple styling library that gives us some standard styles and icons so we can focus most of our effort on the code without sacrificing aesthetics. We've also had numerous customers asking us "How do I use Calcite with [insert native SDK here]?".

The Calcite Design System provides lots of components, styles, icons, and more for the JavaScript developer community, and we've worked hard to build something similar for the Native Maps SDKs. With WPF, WinUI, and .NET MAUI's powerful XAML styling capabilities and markup extensions, we've built a library that does just that. We plan to use it extensively in our demos and samples, and we hope you'll find it useful too.

What's in the SDK:

Implicit or explicit styles that match the Calcite Design System.
Markup extensions with easy access to the over 2500 Calcite UI Icons.

What isn't (currently) in the SDK:

The Calcite set of components. If requested, we'll consider adding some of these in the future.

This offering is built entirely by the ArcGIS Maps SDK for .NET Team and isn't maintained by the Calcite team (albeit with their blessing), and issues and discussions should be handled in our GitHub repository: https://github.com/Esri/calcite-dotnet-toolkit.

Note that even though this library comes from the team that brought you ArcGIS Maps SDK for .NET, there's no dependency on it. You can use this library with any WPF, WinUI, or .NET MAUI application you're building.

We encourage you to read the documentation on available brushes, markup extensions, and how to use them in each framework. We hope you'll try it and let us know where you'd like us to take this effort. At the ESRI Developer and Technology Summit, we'll be hosting a Demo Theater at 2:30 pm on Thursday, March 13, in Demo Theater 3.

Getting started

To get started use your NuGet package explorer, enable pre-release packages for search results, and add one of the following NuGet packages:

Esri.Calcite.WPF
Esri.Calcite.Maui
Esri.Calcite.WinUI

When you add the package, a readme will show you what you need to do to register the package and include the styles.

WPF

In WPF you need to add CalciteResources in App.xaml to the resource dictionary:

<ResourceDictionary>
    <ResourceDictionary.MergedDictionaries>
        <CalciteResources xmlns="http://schemas.esri.com/calcite/2024" />
    </ResourceDictionary.MergedDictionaries>
</ResourceDictionary

Note that additional properties in WPF allow you to set dark mode, or turn off implicit-styling.

WinUI

For WinUI you need to add the CalciteResources to the XamlControlsResources entry. If you don't want implicit styling, you can instead insert the entry before XamlControlsResources:

<XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" >
  <XamlControlsResources.MergedDictionaries>
    <CalciteResources xmlns="using:Esri.Calcite.WinUI" />
  </XamlControlsResources.MergedDictionaries>
</XamlControlsResources>

.NET MAUI

In .NET MAUI, insert the resources after the default style entries to make them implicit, or before to only have the styles available explicitly:

<ResourceDictionary>
    <ResourceDictionary.MergedDictionaries>
        <ResourceDictionary Source="Resources/Styles/Colors.xaml" />
        <ResourceDictionary Source="Resources/Styles/Styles.xaml" />
        <CalciteResources xmlns="http://schemas.esri.com/calcite/2024"/>
    </ResourceDictionary.MergedDictionaries>
</ResourceDictionary>

Additionally in .NET MAUI you must register the Calcite toolkit in the AppBuilder in MauiProgram.cs:

using Esri.Calcite.Maui; // Get access to UseCalcite extension method used below

namespace MauiTests
{
    public static class MauiProgram
    {
        public static MauiApp CreateMauiApp()
        {
            var builder = MauiApp.CreateBuilder();
            builder
                .UseMauiApp<App>()
                .ConfigureFonts(fonts =>
                {
                    fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
                    fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
                }).UseCalcite(); // Register Calcite

            return builder.Build();
        }
    }
}

Usage

With the inclusion of the resources, you'll get access to a range colors, brushes, styles, and icons, which enables you to style your application following the Calcite design system guidelines. If you're familiar with the Calcite design tokens, you'll find many equivalences and naming similarities, with only slight adaptations to naming patterns used in XAML. For instance, if you want to create a Primary and Secondary Calcite button apply the styles in the following way:

<Button Content="OK" Style="{StaticResource CalcitePrimaryButtonStyle}" />
<Button Content="Cancel" Style="{StaticResource CalciteSecondaryButtonStyle}" />

The naming of styles generally follows the pattern of Calcite[Kind][ControlType]Style matching the naming patterns of other XAML styles provided by the platform. The last word is always the type of the resource, in this case, a "Style". Similarly, you'll find brushes like "CalciteBrandBrush" and "CalciteBrandColor" each of type Brush and Color (note that on MAUI colors have additional 'Light' or 'Dark' appended since colors don't support theming. For example CalciteBrandLightColor). You can find more information on these here:

Full list of brushes: https://github.com/Esri/calcite-dotnet-toolkit/blob/main/docs/brushes.md
WPF Styles: https://github.com/Esri/calcite-dotnet-toolkit/blob/main/docs/wpf.md#control-styles
WinUI: https://github.com/Esri/calcite-dotnet-toolkit/blob/main/docs/winui.md#control-styles (WinUI uses light-weight styling and thus mostly override style brushes instead of entire styles)
.NET MAUI styles: https://github.com/Esri/calcite-dotnet-toolkit/blob/main/docs/maui.md#control-styles

Icons

We also included the over 2500 Calcite UI icons in all 3 levels of detail for crisp locking icons at any size. These range from a wealth of generic icons, to lots of GIS related icons.

You can access these either via a font and a character code, or using the markup extensions provided by the library. Here's a few examples of what that might look like in your XAML:

WPF:

<TextBlock Text="{StaticResource CalciteUIIcons_Glyph_Map}" 
           FontFamily="{StaticResource CalciteUIIconsMediumFontFamily}" />
<Path Data="{calcite:CalciteIconGeometry Icon=ChevronLeft, Scale=Small}" Fill="Green" Width="32" Height="32" Stretch="Uniform" />
<Image Source="{calcite:CalciteIconImage Icon=AddLayer, Scale=Large, SymbolSize=32, Brush=Blue}" Width="32" Height="32" />

WinUI:

<TextBlock Text="{StaticResource CalciteUIIcons_Glyph_Map}" 
           FontFamily="{StaticResource CalciteUIIconsMediumFontFamily}" />

<IconSourceElement Width="32" Height="32" >
    <IconSourceElement.IconSource>
        <calcite:CalciteFontIconSource Icon="Map" FontSize="32" Scale="Large" />
    </IconSourceElement.IconSource>
</IconSourceElement>

<AppBarButton Label="Zoom Out">
    <AppBarButton.Icon>
        <IconSourceElement IconSource="{calcite:CalciteIconSource Icon=ZoomOutFixed, Scale=Small}" />
    </AppBarButton.Icon>
</AppBarButton>

.NET MAUI:

<Label Text="{StaticResource CalciteUIIcons_Glyph_Map}" 
	   FontFamily="CalciteUIIconsMediumFontFamily" />
<Image>
    <Image.Source>
        <calcite:CalciteIconImageSource Color="Blue" Icon="MagnifyingGlass" Size="40" Scale="Large" />
    </Image.Source>
</Image>
<Image Source="{calcite:CalciteIconImage Color=Blue, Icon=MagnifyingGlass,Size=40, Scale=Large}" />

Dark Mode

WinUI and .NET MAUI fully supports dark and light modes. However, this feature is not fully implemented in WPF itself, so the Calcite Toolkit for .NET has implemented its own way of handling this. You can explicitly set Dark and LightMode on the CalciteResources, or leave it default and the mode will follow the system settings. Note though that if you have hardcoded brushes that don't update when switching to darkmode, you will need to switch to using Calcite brushes that auto-update on mode changes.

Samples

Most of our Demo samples have been updated to use the library, and we added a new big map viewer sample that pulls together most of our SDK and the Calcite styling to create a full fledged application. Check out our samples today: https://github.com/Esri/arcgis-runtime-demos-dotnet/

(view in My Videos)

What's next

This is our first preview of this exciting new offering. We're looking forward to hearing your feedback on what's missing, what could be better, and how you use it, so we can continue building this out to support the XAML developer community in building great-looking applications.

ViktorSafar

We (dozens of projects/40 devs) in ~95% of cases build apps that have completely custom UI. Applies to both web and desktop . Especially desktop. Have yet to come across a customer that would want to pay for a custom app that looks like Esri UI.

I do see a potential value in Calcite when building PoCs. For us, that does not happen very often though.

dotMorten_esri

@ViktorSafar That's totally fair. Which is why you don't have to use the implicit styles - you can reference the toolkit without getting the implicit styles and get quick access to the huge symbol library for instance. The implicit styles are also somewhat subtle, and you can override the blue brand color. For WPF you get a more modern look rather than the outdated WPF defaults, but MAUI and WinUI already have that modern look so the difference there is smaller.
I wouldn't even say that by just using the implicit styles it looks like an esri app - it really comes down to how you build your app up whether that would be the case.