How to use Windows Community Toolkit - Version 8.x

This tutorial will walk you through adding and implementing the SettingsCard control but the same steps can be followed for other* Windows Community Toolkit controls version 8.x.

* See the non-Windows platform compatibility section for more details.

Note

The complete source code that goes along with this guide is available in the unoplatform/Uno.Samples GitHub repository - SettingsCard Sample

Prerequisites

For a step-by-step guide to installing the prerequisites for your preferred IDE and environment, consult the Get Started guide.

Tip

If you are unsure of the version of the Windows Community Toolkit to use between v7 and v8, make sure to read the details about the Windows Community Toolkit migration guide.

NuGet Packages

Uno Platform is now supported out of the box by the Windows Community Toolkit and Windows Community Toolkit Labs starting with version 8.x.

Important

If you are already using Windows Community Toolkit version 7.x in your Uno Platform project and want to update to version 8.x, note that Uno Platform has its own fork of the Windows Community Toolkit for version 7.x.

In your project, these Windows Community Toolkit Uno packages were referenced behind a conditional to allow for use on Windows, Android, iOS, mac Catalyst, Linux, and WebAssembly.

Conditional references are no longer necessary with version 8.x, you can remove the Uno Windows Community Toolkit references and all Condition statements around the packages.

Referencing the Windows Community Toolkit

When using the Uno Platform solution templates, add the following to your application:

1. Install the NuGet package(s) reference(s) that you need

   • Single Project Template [WinUI / WinAppSDK]
   • Multi-Head Project Template (Legacy) [WinUI / WinAppSDK]
   • Multi-Head Project Template (Legacy) [UWP]
   • Shared Project (.shproj) Template (Legacy) [WinUI / WinAppSDK]
   • Shared Project (.shproj) Template (Legacy) [UWP]

   1. Edit your project file PROJECT_NAME.csproj and add the needed reference(s):

      <ItemGroup>
        <PackageReference Include="CommunityToolkit.WinUI.Controls.SettingsControls" />
        <!-- Add more community toolkit references here -->
      </ItemGroup>
      

   2. Edit Directory.Packages.props and add the needed reference(s):

      <ItemGroup>
        <PackageVersion Include="CommunityToolkit.WinUI.Controls.SettingsControls" Version="8.1.240916" />
        <!-- Add more community toolkit references here -->
      </ItemGroup>
      

   Note

   Windows Community Toolkit version 8.x requires an update to Windows SDK 10.0.22621 and above, along with Microsoft.WindowsAppSDK updated to the latest matching version.

   To override these versions within a single project structure, you can set the properties in the Directory.Build.props file or directly in your project's csproj file. For more detailed information, please see the implicit packages details.

   For example, in PROJECT_NAME.csproj:

   <TargetFrameworks>
     <!-- Code for other TargetFrameworks omitted for brevity -->
     net8.0-windows10.0.22621;
   </TargetFrameworks>
   

   <PropertyGroup>
     <WindowsSdkPackageVersion>10.0.22621.38</WindowsSdkPackageVersion>
     <WinAppSdkVersion>1.5.240607001</WinAppSdkVersion>
   </PropertyGroup>
   

2. Add the related needed namespace(s)

   Note

   In WCT version 8.x, the namespaces between UWP and WinAppSDK were merged.

   WinUI / WinAppSDK / UWP

   In XAML:
   xmlns:controls="using:CommunityToolkit.WinUI.Controls"

   In C#:
   using CommunityToolkit.WinUI.Controls;

Example with the SettingsCard Control

SettingsCard is a control that can be used to display settings in your experience. It uses the default styling found in Windows 11 and is easy to use, meets all accessibility standards and will make your settings page look great!

You can set the Header, HeaderIcon, Description, and Content properties to create an easy to use experience, like so:

<controls:SettingsCard Description="This is a default card, with the Header, HeaderIcon, Description and Content set."
                       Header="This is the Header">
  <controls:SettingsCard.HeaderIcon>
    <FontIcon Glyph="&#xE799;"
              FontFamily="{ThemeResource SymbolThemeFontFamily}" />
  </controls:SettingsCard.HeaderIcon>
  <ComboBox SelectedIndex="0">
    <ComboBoxItem>Option 1</ComboBoxItem>
    <ComboBoxItem>Option 2</ComboBoxItem>
    <ComboBoxItem>Option 3</ComboBoxItem>
  </ComboBox>
</controls:SettingsCard>

See a working sample with more examples

A complete working sample, along with additional examples, is available on GitHub: Uno Windows Community Toolkit SettingsCard Sample

---

Tip

Take a look at our common issues list if you're having any troubles.

If you are experiencing issues with Uno Platform, please visit our GitHub Discussions or Discord Server - where our engineering team and community will be able to help you.