doc/articles/uno-community-toolkit-v8.md
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 -
SettingsCardSample
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.
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, Linux, and WebAssembly.
Conditional references are no longer necessary with version 8.x, you can remove the Uno Windows Community Toolkit references and all
Conditionstatements around the packages.
When using the Uno Platform solution templates, add the following to your application:
Install the NuGet package(s) reference(s) that you need
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>
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.propsfile or directly in your project'scsprojfile. For more detailed information, please see the implicit packages details.For example, in
PROJECT_NAME.csproj:xml<TargetFrameworks> <!-- Code for other TargetFrameworks omitted for brevity --> net10.0-windows10.0.22621; </TargetFrameworks>xml<PropertyGroup> <WindowsSdkPackageVersion>10.0.22621.38</WindowsSdkPackageVersion> <WinAppSdkVersion>1.5.240607001</WinAppSdkVersion> </PropertyGroup>
Edit your project file PROJECT_NAME.csproj and add the needed reference(s):
<ItemGroup>
<PackageReference 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.
Select the following projects for installation and add the needed reference(s) to each of them:
PROJECT_NAME.Windows.csprojPROJECT_NAME.Wasm.csprojPROJECT_NAME.Mobile.csproj (or PROJECT_NAME.iOS.csproj, PROJECT_NAME.Droid.csproj, and PROJECT_NAME.macOS.csproj if you have an existing project)PROJECT_NAME.Skia.Gtk.csprojPROJECT_NAME.Skia.WPF.csproj<ItemGroup>
<PackageReference Include="CommunityToolkit.WinUI.Controls.SettingsControls" Version="8.1.240916" />
<!-- Add more uno 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.
Add the related needed namespace(s)
In XAML:
xmlns:controls="using:CommunityToolkit.WinUI.Controls"
In C#:
using CommunityToolkit.WinUI.Controls;
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=""
FontFamily="{ThemeResource SymbolThemeFontFamily}" />
</controls:SettingsCard.HeaderIcon>
<ComboBox SelectedIndex="0">
<ComboBoxItem>Option 1</ComboBoxItem>
<ComboBoxItem>Option 2</ComboBoxItem>
<ComboBoxItem>Option 3</ComboBoxItem>
</ComboBox>
</controls:SettingsCard>
A complete working sample, along with additional examples, is available on GitHub: Uno Windows Community Toolkit SettingsCard Sample
The CommunityToolkit provides a collection of ready-to-use converters for various scenarios (e.g., x:Bind in XAML). These converters streamline development by offering implementations for commonly used functionality, eliminating the need to manually create basic converters.
List of CommunityToolkit Converters | Windows Toolkit Documentation
The implementation of these is similar to the example of the SettingsControl above, with some minor adjustments required to use them:
Install the NuGet package reference needed for the converters
Edit your project file PROJECT_NAME.csproj and add this additional needed reference:
<ItemGroup>
<PackageReference Include="CommunityToolkit.WinUI.Converters" />
<!-- Add more community toolkit references here -->
</ItemGroup>
Edit Directory.Packages.props and add this additional needed reference:
<ItemGroup>
<PackageVersion Include="CommunityToolkit.WinUI.Converters" Version="8.1.240916" />
<!-- Add more community toolkit references here -->
</ItemGroup>
Add the related needed namespace(s)
In XAML:
xmlns:converters="using:CommunityToolkit.WinUI.Converters"
In C#:
using CommunityToolkit.WinUI.Converters;
If you are developing an app using C# Markup and want to use the converters, you can refer to the C# Markup Converters Documentation for a detailed usage guide. The general import process is covered from this point onward.
XAML Definition
Unlike the previously seen SettingsCard control example, it is standard practice to define a converter in the Page.Resources section as a StaticResource before using it. This approach ensures that converters, like controls, are properly declared with a namespace and can be easily reused throughout the page.
The StringToVisibilityConverter is a converter that transforms a string value into a Visibility state, returning Visibility.Visible for non-empty strings and Visibility.Collapsed for null or empty strings.
Add the converter to the Page.Resources section as a StaticResource:
<Page.Resources>
<converters:StringToVisibilityConverter x:Key="StringToVisibilityConverter" />
</Page.Resources>
Here is an example of how to use the converter in your XAML content:
<TextBlock Text="This text is visible only if the condition is met."
Visibility="{Binding SomeStringProperty, Converter={StaticResource StringToVisibilityConverter}}"/>
The BoolToObjectConverter allows you to convert a boolean value into a specific object by defining TrueObject and FalseObject. Depending on the boolean value, the converter will return the corresponding object.
For example, you can use it to switch colors dynamically.
Add the converter to the Page.Resources section as a StaticResource:
<Page.Resources>
<converters:BoolToObjectConverter x:Key="BoolToColorConverter"
TrueObject="Green"
FalseObject="Red"/>
</Page.Resources>
Here is an example of how to use the converter in your XAML content:
<TextBlock Text="Status:"
Foreground="{Binding IsValid, Converter={StaticResource BoolToColorConverter}}"/>
In this example, the TextBlock background will be green when IsValid is true and red when IsValid is false.
[!includegetting-help]