How to use Windows Community Toolkit

The Windows Community Toolkit is a collection of helper functions, custom controls, and app services. It simplifies and demonstrates common developer patterns when building experiences for Windows 10.

This tutorial will walk through adding and implementing the DataGrid control but the steps can be followed for any of the Uno ported Windows Community Toolkit controls.

Tip

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

Tip

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

NuGet Packages for Uno Platform

Uno Platform has ported the Windows Community Toolkit 7.x for use in Uno Platform applications to allow for use on Windows, Android, iOS, mac Catalyst, Linux, and WebAssembly.

The following packages are available:

Referencing the Windows Community Toolkit

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

Add the following conditional references:

<ItemGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'windows'">
  <PackageReference Include="CommunityToolkit.WinUI.UI.Controls" Version="7.1.2" />
  <!-- Add more community toolkit references here -->
</ItemGroup>
<ItemGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) != 'windows'">
  <PackageReference Include="Uno.CommunityToolkit.WinUI.UI.Controls" Version="7.1.200" />
  <!-- Add more uno community toolkit references here -->
</ItemGroup>

If you already had a reference to the Community Toolkit, you should remove those lines:

<ItemGroup>
  <PackageReference Include="Uno.CommunityToolkit.WinUI.UI.Controls" Version="7.1.2" />
</ItemGroup>

If your're getting an error like this one :

Controls\TextBox\Themes\Generic.xaml : Xaml Internal Error error WMC9999: 
Type universe cannot resolve assembly: Uno.UI, Version=255.255.255.255, 
Culture=neutral, PublicKeyToken=null.

This means that there's an unconditional reference to Uno Platform's packages, and you'll need to make sure to add the conditional references as suggested above.

Task 1 - Add Windows Community Toolkit to Uno Projects

  1. Install Nuget package for targeted control
    datagrid-nuget

    Note

    For UWP and WinUI 3 projects, you should use the packages published by Microsoft that are not prefixed with Uno.*.

  2. Add a reference to the UWP UI Controls

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

In C#:
using CommunityToolkit.WinUI.UI.Controls;

Task 2 - Add the DataGrid Control

This control will create an easily organized grid that will allow you to create flexible columns and rows.

  1. Begin by adding the control using the syntax below. Change the x:Name to the name of your DataGrid.
    <controls:DataGrid x:Name="dataGrid"></controls:DataGrid>

  2. Similar to how you would configure columns for a XAML Grid layout, you can add column definitions within your DataGrid control:

    <controls:DataGrid.Columns>
    <controls:DataGridTextColumn Header="Rank"/>
    <controls:DataGridComboBoxColumn Header="Mountain"/>
</controls:DataGrid.Columns>

    This will create two columns that can be adjusted by the user. datagrid-column-gif

    Alternatively, you can use the AutoGenerateColumns attribute on your DataGrid control if you do not know how many columns your data will require.

    <controls:DataGrid x:Name="dataGrid" AutoGenerateColumns="True" />

  3. Format your rows in the same way as your columns or use a DataTemplate added as an attribute on the DataGrid control:

    <controls:DataGrid x:Name="dataGrid" RowDetailsTemplate="{StaticResource RowDetailsTemplate}">

  4. Data can be added with data binding. First, add your ItemsSource as a property of your DataGrid control.

    <controls:DataGrid x:Name="dataGrid" ItemsSource="{x:Bind MyViewModel.Customers}" />

    Then, set the binding on each column:

    <controls:DataGrid.Columns>
    <controls:DataGridTextColumn Header="Rank" Binding="{Binding Rank}" Tag="Rank" />
    <controls:DataGridTextColumn Header="Mountain" Binding="{Binding Mountain}" Tag="Mountain" />
</controls:DataGrid.Columns>

See a working example with data

datagrid-full-sample

A working sample complete with data is available on GitHub: Uno Windows Community Toolkit 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.