31. Extended control modules and component gallery

Goal

Why this matters

Prerequisites

1. Survey of extended control namespaces

Avalonia groups advanced controls into focused namespaces:

Module Namespace Highlights
Color editing Avalonia.Controls.ColorPicker ColorPicker, ColorView, palette data, HSV/RGB components
Refresh gestures Avalonia.Controls.PullToRefresh RefreshContainer, RefreshVisualizer, RefreshInfoProvider
Notifications Avalonia.Controls.Notifications WindowNotificationManager, NotificationCard, INotification
Date & time Avalonia.Controls.DateTimePickers DatePicker, TimePicker, presenters, culture support
Interactive navigation Avalonia.Controls.SplitView, Avalonia.Controls.SplitButton Collapsible panes, hybrid buttons
Document text Avalonia.Controls.Documents Inline elements (Run, Bold, InlineUIContainer)
Misc UX Avalonia.Controls.TransitioningContentControl, Avalonia.Controls.Notifications.ReversibleStackPanel, Avalonia.Controls.Primitives helpers

Each module ships styles in Fluent/Simple theme dictionaries. Include the relevant .axaml resource dictionaries when building custom themes.

2. ColorPicker and color workflows

ColorPicker extends ColorView by providing a preview area and flyout editing UI (ColorPicker.cs). Key elements:

Usage snippet:

<ColorPicker SelectedColor="{Binding AccentColor, Mode=TwoWay}">
  <ColorPicker.ContentTemplate>
    <DataTemplate>
      <StackPanel Orientation="Horizontal" Spacing="8">
        <Border Width="24" Height="24" Background="{Binding}" CornerRadius="4"/>
        <TextBlock Text="{Binding Converter={StaticResource RgbFormatter}}"/>
      </StackPanel>
    </DataTemplate>
  </ColorPicker.ContentTemplate>
</ColorPicker>

Tips:

3. Pull-to-refresh infrastructure

RefreshContainer wraps scrollable content and coordinates RefreshVisualizer animations (RefreshContainer.cs). Concepts:

Example:

<ptr:RefreshContainer RefreshRequested="OnRefresh">
  <ptr:RefreshContainer.Visualizer>
    <ptr:RefreshVisualizer Orientation="TopToBottom"
                            Content="{DynamicResource PullHintTemplate}"/>
  </ptr:RefreshContainer.Visualizer>
  <ScrollViewer>
    <ItemsControl ItemsSource="{Binding FeedItems}"/>
  </ScrollViewer>
</ptr:RefreshContainer>

private async void OnRefresh(object? sender, RefreshRequestedEventArgs e)
{
    using var deferral = e.GetDeferral();
    await ViewModel.LoadLatestAsync();
}

Notes:

4. Notifications and toast UIs

WindowNotificationManager hosts toast-like notifications overlaying a TopLevel (WindowNotificationManager.cs).

Custom template example:

<Style Selector="NotificationCard">
  <Setter Property="Template">
    <Setter.Value>
      <ControlTemplate TargetType="NotificationCard">
        <Border Classes="toast" CornerRadius="6" Background="{ThemeResource SurfaceBrush}">
          <StackPanel Orientation="Vertical" Margin="12">
            <TextBlock Text="{Binding Content.Title}" FontWeight="SemiBold"/>
            <TextBlock Text="{Binding Content.Message}" TextWrapping="Wrap"/>
            <Button Content="Dismiss" Classes="subtle"
                    notifications:NotificationCard.CloseOnClick="True"/>
          </StackPanel>
        </Border>
      </ControlTemplate>
    </Setter.Value>
  </Setter>
</Style>

Considerations:

5. DatePicker/TimePicker for forms

DatePicker and TimePicker share presenters and respect culture-specific formats (DatePicker.cs, TimePicker.cs).

Validation strategies:

Calendar control for planners

Calendar gives you a full month or decade view without the flyout wrapper.

When you need both Calendar and DatePicker, reuse the same CalendarDatePicker styles so typography and spacing stay consistent.

6. SplitView and navigation panes

SplitView builds side drawers with flexible display modes (SplitView.cs).

Usage example:

<SplitView IsPaneOpen="{Binding IsMenuOpen, Mode=TwoWay}"
           DisplayMode="CompactOverlay"
           PanePlacement="Left"
           CompactPaneLength="56"
           OpenPaneLength="240">
  <SplitView.Pane>
    <StackPanel>
      <Button Content="Dashboard" Command="{Binding GoHome}"/>
      <Button Content="Reports" Command="{Binding GoReports}"/>
    </StackPanel>
  </SplitView.Pane>
  <Frame Content="{Binding CurrentPage}"/>
</SplitView>

Tips:

TransitioningContentControl for dynamic views

TransitioningContentControl wraps a content presenter with IPageTransition support.

For component galleries, use it to showcase before/after states or responsive layouts without writing manual animation plumbing.

7. SplitButton and ToggleSplitButton

SplitButton provides a main action plus a secondary flyout (SplitButton.cs).

Example:

<SplitButton Content="Export"
             Command="{Binding ExportAll}">
  <SplitButton.Flyout>
    <MenuFlyout>
      <MenuItem Header="Export CSV" Command="{Binding ExportCsv}"/>
      <MenuItem Header="Export JSON" Command="{Binding ExportJson}"/>
    </MenuFlyout>
  </SplitButton.Flyout>
</SplitButton>

Ensure Command.CanExecute updates by binding to view model state; SplitButton listens for CanExecuteChanged and toggles IsEnabled accordingly.

8. Notifications, documents, and media surfaces

MediaPlayerElement (available when you reference the media package) embeds audio/video playback with transport controls.

Create a ComponentGalleryWindow that showcases each control with explanations and theme toggles:

<TabControl>
  <TabItem Header="Color">
    <StackPanel Spacing="16">
      <TextBlock Text="ColorPicker" FontWeight="SemiBold"/>
      <ColorPicker SelectedColor="{Binding ThemeColor}"/>
    </StackPanel>
  </TabItem>
  <TabItem Header="Refresh">
    <ptr:RefreshContainer RefreshRequested="OnRefreshRequested">
      <ListBox ItemsSource="{Binding Items}"/>
    </ptr:RefreshContainer>
  </TabItem>
  <TabItem Header="Notifications">
    <StackPanel>
      <Button Content="Show success" Click="OnShowSuccess"/>
      <TextBlock Text="Notifications appear top-right"/>
    </StackPanel>
  </TabItem>
</TabControl>

Best practices:

10. Practice lab: responsibility matrix

  1. Color workflows – Customize ColorPicker palettes, bind to view model state, and expose automation peers for UI tests.
  2. Mobile refresh – Implement RefreshContainer in a list, test on touch-enabled hardware, and add fallback commands for desktop.
  3. Toast scenarios – Build a notification service that queues messages and exposes dismissal commands, then craft styles for different severities.
  4. Dashboard shell – Combine SplitView, SplitButton, and TransitioningContentControl to create a responsive navigation shell with keyboard and pointer parity.
  5. Component gallery – Document each control with design notes, theming tweaks, and automation IDs; integrate into project documentation.

Troubleshooting & best practices

Look under the hood (source bookmarks)

Check yourself

What's next