Uno Toolkit Controls and Helpers

Patterns for the Uno.Toolkit.UI library: controls, helpers, and responsive extensions that work cross-platform on iOS, Android, macOS, Linux, Windows, and WebAssembly.

Installation

Add Toolkit to UnoFeatures in your .csproj:

<UnoFeatures>
    Material;
    Toolkit;
</UnoFeatures>

XAML namespace: xmlns:utu="using:Uno.Toolkit.UI"

Controls

AutoLayout

Bridges Figma Auto Layout to WinUI. Prefer over StackPanel for consistent spacing without per-child margins.

<utu:AutoLayout Spacing="16" Padding="24"
                PrimaryAxisAlignment="Center"
                Orientation="Vertical">
    <TextBlock Text="Title" Style="{StaticResource TitleLarge}" />
    <TextBlock Text="Subtitle" Style="{StaticResource BodyMedium}" />
</utu:AutoLayout>

Key Properties: Spacing, Padding, PrimaryAxisAlignment, CounterAxisAlignment, Orientation, Justify (stretch children to fill), IsReverseZIndex

Per-child overrides: AutoLayout.PrimaryAlignment, AutoLayout.CounterAlignment, AutoLayout.PrimaryLength, AutoLayout.CounterLength

NavigationBar

Cross-platform navigation bar. Use with Uno Navigation Extensions for automatic back-button behavior.

<utu:NavigationBar Content="Page Title">
    <utu:NavigationBar.MainCommand>
        <AppBarButton>
            <AppBarButton.Icon>
                <BitmapIcon UriSource="ms-appx:///Assets/Icons/back.png" />
            </AppBarButton.Icon>
        </AppBarButton>
    </utu:NavigationBar.MainCommand>
    <utu:NavigationBar.PrimaryCommands>
        <AppBarButton Icon="Setting" Label="Settings" />
    </utu:NavigationBar.PrimaryCommands>
</utu:NavigationBar>

SafeArea

Handles notches, status bars, and rounded corners on mobile devices. Wrap page content to avoid overlap.

<utu:SafeArea Insets="Top,Bottom">
    <Grid>
        <!-- Page content here -->
    </Grid>
</utu:SafeArea>

Modes: Padding (default, adds padding), InsetMask (clips to safe area), SoftInput (adjusts for keyboard)

TabBar

Lateral navigation control. Integrates with Uno Navigation Extensions via UseToolkitNavigation().

<utu:TabBar SelectedIndex="0">
    <utu:TabBarItem Content="Home">
        <utu:TabBarItem.Icon>
            <FontIcon Glyph="&#xE80F;" />
        </utu:TabBarItem.Icon>
    </utu:TabBarItem>
    <utu:TabBarItem Content="Search">
        <utu:TabBarItem.Icon>
            <FontIcon Glyph="&#xE721;" />
        </utu:TabBarItem.Icon>
    </utu:TabBarItem>
</utu:TabBar>

Card and CardContentControl

Material Design card surfaces. Use CardContentControl for actionable cards with elevation.

<utu:CardContentControl Style="{StaticResource ElevatedCardContentControlStyle}">
    <StackPanel Padding="16" Spacing="8">
        <TextBlock Text="Card Title" Style="{StaticResource TitleMedium}" />
        <TextBlock Text="Card content goes here" Style="{StaticResource BodyMedium}" />
    </StackPanel>
</utu:CardContentControl>

Chip and ChipGroup

Compact interactive elements for filters, tags, or selections.

<utu:ChipGroup SelectionMode="Multiple"
               ItemsSource="{Binding FilterOptions}"
               SelectedItems="{Binding SelectedFilters, Mode=TwoWay}">
    <utu:ChipGroup.ChipTemplate>
        <DataTemplate>
            <utu:Chip Content="{Binding Name}" />
        </DataTemplate>
    </utu:ChipGroup.ChipTemplate>
</utu:ChipGroup>

DrawerControl

Hidden pane revealed by swipe gesture.

<utu:DrawerControl OpenDirection="Left" DrawerLength="300">
    <utu:DrawerControl.DrawerContent>
        <Grid Background="{ThemeResource SurfaceBrush}">
            <!-- Drawer menu -->
        </Grid>
    </utu:DrawerControl.DrawerContent>
    <!-- Main page content -->
</utu:DrawerControl>

LoadingView

Indicates async loading state. Use with MVUX Feeds for automatic loading/error/data states.

<utu:LoadingView Source="{Binding DataFeed}">
    <utu:LoadingView.LoadingContent>
        <ProgressRing IsActive="True" />
    </utu:LoadingView.LoadingContent>
    <DataTemplate>
        <TextBlock Text="{Binding}" />
    </DataTemplate>
</utu:LoadingView>

Helpers

ResponsiveExtension

Adapt property values based on screen width. Breakpoints: Narrowest (150), Narrow (300), Normal (600), Wide (800), Widest (1080).

<TextBlock Text="{utu:Responsive Narrow='Mobile View', Wide='Desktop View'}" />
<Grid ColumnSpacing="{utu:Responsive Narrow=8, Wide=24}" />

Custom breakpoints:

<Page.Resources>
    <utu:ResponsiveLayout x:Key="CustomLayout" Narrow="400" Wide="800" />
</Page.Resources>
<TextBlock Text="{utu:Responsive Layout={StaticResource CustomLayout},
                                Narrow=Small, Wide=Large}" />

CommandExtensions

Attach commands to any control without code-behind.

<Border utu:CommandExtensions.Command="{Binding TapCommand}">
    <TextBlock Text="Tappable area" />
</Border>

ItemsRepeaterExtensions

Add selection support to ItemsRepeater (which lacks it natively).

<muxc:ItemsRepeater ItemsSource="{Binding Items}"
                    utu:ItemsRepeaterExtensions.SelectedItem="{Binding SelectedItem, Mode=TwoWay}">

StatusBar

Control mobile status bar appearance per page.

<Page utu:StatusBar.Foreground="Light"
      utu:StatusBar.Background="{ThemeResource PrimaryBrush}">

Common Mistakes

• Using StackPanel with per-child Margin instead of AutoLayout with Spacing
• Forgetting SafeArea on pages with NavigationBar, causing content to render behind the notch
• Not calling UseToolkitNavigation() when using TabBar with Uno Navigation Extensions
• Hardcoding breakpoint values instead of using ResponsiveExtension
• Using AppBarButton outside of CommandBar - use regular Button with icon instead

Detailed References

• references/01-layout-controls.md - Read when using AutoLayout, SafeArea, or DrawerControl
• references/02-navigation-controls.md - Read when using NavigationBar, TabBar, or TabBarItem
• references/03-data-controls.md - Read when using Card, Chip, ChipGroup, or LoadingView
• references/04-helpers-extensions.md - Read when using ResponsiveExtension, CommandExtensions, ItemsRepeaterExtensions, or StatusBar