syncfusion-winui-color-palette（Synfusion WinUI 调色板）

When to Use This Skill

Use this skill immediately when the user:

• Needs to implement a color palette (swatch-based) UI in WinUI applications
• Wants to display theme colors with their variant shades
• Needs to show standard colors with or without color shade variants
• Requires adding custom colors to the theme or standard color palette
• Wants to open a More Colors dialog for extended color selection
• Needs a "No Color" (transparent) selection option
• Wants to track recently used colors from the More Colors dialog
• Needs to set or get the selected color programmatically via SelectedBrush
• Requires customizing palette headers, header templates, or color shade spacing
• Needs to change layout flow direction or foreground styling
• Wants to set an automatic/default color that users can restore easily

This skill is specifically for the Syncfusion WinUI Color Palette control (SfColorPalette), not for gradient-based or spectrum-based color pickers.

Component Overview

The SfColorPalette is a WinUI control that provides a swatch-based color selection interface. It supports:

• Theme Colors: Built-in palette themes (Office, Yellow, Green, etc.) with variant shades
• Standard Colors: Fixed set of standard colors with optional shade variants
• Custom Colors: Add your own colors to theme or standard palettes
• More Colors Dialog: Extended selection via color spectrum with opacity control
• Recent Colors: Tracks colors selected from the More Colors dialog
• Automatic Color: Default/automatic color button with configurable color
• No Color Option: Transparent color selection button
• Tooltip Support: Color name shown on hover
• Programmatic Access: Get/set selected color via SelectedBrush
• Event Notifications: SelectedBrushChanged for real-time change detection

Key Namespace:

using Syncfusion.UI.Xaml.Editors;

NuGet Package:

Syncfusion.Editors.WinUI

Documentation and Navigation Guide

Getting Started with SfColorPalette

📄 Read: references/getting-started.md

Read this reference when you need:

• Installation and NuGet package setup instructions
• Basic SfColorPalette control implementation
• Namespace and assembly references
• Accessing and setting selected color programmatically
• Handling the SelectedBrushChanged event
• Showing/hiding No Color button
• First working XAML + C# example with minimal configuration

Topics covered:

• Creating a WinUI 3 desktop application
• Adding Syncfusion.Editors.WinUI NuGet package
• Importing the control namespace
• Basic XAML and C# initialization
• SelectedBrush property (get/set)
• SelectedBrushChanged event handling
• ShowNoColorButton property
• ShowMoreColorsButton property
• RecentColors collection
• Control structure overview

Theme Colors

📄 Read: references/theme-colors.md

Read this reference when you need:

• Selecting colors from built-in theme palettes
• Switching the active theme palette at runtime
• Adding custom colors to the theme palette
• Showing or hiding base theme colors
• Showing or hiding theme color variant shades
• Customizing the theme palette header text or template
• Hiding the theme palette header
• Adjusting spacing between base colors and their variants

Topics covered:

• ActivePalette property and available ColorPaletteNames
• PaletteColors property (ColorPaletteModel)
• PaletteColors.ShowColors — show/hide base theme colors
• PaletteColors.ShowColorShades — show/hide variant shades
• PaletteColors.Colors — adding custom ColorModel entries
• PaletteColors.Header — custom header text
• PaletteColors.ShowHeader — header visibility
• PaletteColors.HeaderTemplate — custom header UI
• PaletteColors.ColorShadesSpacing — variant spacing
• Hiding the entire theme palette

Standard Colors

📄 Read: references/standard-colors.md

Read this reference when you need:

• Selecting colors from the built-in standard colors panel
• Adding custom colors to the standard color palette
• Showing or hiding standard color variant shades
• Hiding the standard colors panel entirely
• Customizing the standard palette header text or template
• Hiding the standard palette header
• Adjusting spacing between standard colors and their variants

Topics covered:

• StandardColors property (StandardPaletteModel)
• StandardColors.ShowColors — show/hide standard colors
• StandardColors.ShowColorShades — show/hide variant shades
• StandardColors.Colors — adding custom ColorModel entries
• StandardColors.Header — custom header text
• StandardColors.ShowHeader — header visibility
• StandardColors.HeaderTemplate — custom header UI
• StandardColors.ColorShadesSpacing — variant spacing
• Hiding the entire standard colors panel

More Color Dialog

📄 Read: references/more-color-dialog.md

Read this reference when you need:

• Enabling or disabling the More Colors button
• Understanding how the More Colors dialog works
• Hiding the More Colors option to restrict color choices

Topics covered:

• ShowMoreColorsButton property
• Selecting custom colors from the color spectrum dialog
• Hiding the More Colors button

UI Customization

📄 Read: references/ui-customization.md

Read this reference when you need:

• Setting or getting the selected color programmatically
• Setting a null/transparent color value
• Configuring the automatic (default) color button
• Hiding the default color button
• Customizing palette header foreground color
• Changing flow direction (right-to-left support)
• Understanding tooltip behavior for color items
• Working with recently used colors panel

Topics covered:

• SelectedBrush property (programmatic access)
• Setting null/transparent color (Colors.Transparent)
• AutomaticBrush property — default color configuration
• ShowDefaultColorButton property — default color button visibility
• Foreground property — header text color
• FlowDirection property — RTL support
• Tooltip behavior for color items
• RecentColors collection — recently used colors

Best Practices and Troubleshooting

📄 Read: references/best-practices.md

Read this reference when you need:

• Guidance on when to use SfColorPalette vs SfColorPicker
• Common implementation patterns and use cases
• Troubleshooting color selection or display issues
• Understanding edge cases and limitations
• Accessibility considerations
• Integration with flyouts, dialogs, and property panels

Topics covered:

• When to use palette vs picker
• Common use cases (theme selector, document editor, drawing tool)
• Troubleshooting guide
• Edge cases to avoid
• Accessibility best practices
• Integration patterns (flyout, dialog, property panel)

Quick Start Example

Here's a minimal example to get started with SfColorPalette:

XAML Implementation

<Page
    x:Class="ColorPaletteApp.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:editors="using:Syncfusion.UI.Xaml.Editors">

    <Grid Padding="20">
        <!-- Basic Color Palette -->
        <editors:SfColorPalette
            x:Name="colorPalette"
            ShowMoreColorsButton="True"
            ShowNoColorButton="True"
            SelectedBrushChanged="ColorPalette_SelectedBrushChanged" />
    </Grid>
</Page>

C# Code-Behind

using Syncfusion.UI.Xaml.Editors;
using Microsoft.UI.Xaml.Media;
using Windows.UI;

namespace ColorPaletteApp
{
    public sealed partial class MainPage : Page
    {
        public MainPage()
        {
            this.InitializeComponent();
        }

        private void ColorPalette_SelectedBrushChanged(object sender, SelectedBrushChangedEventArgs e)
        {
            var oldBrush = e.OldBrush;
            var newBrush = e.NewBrush;

            // Apply selected color to a target element
            if (newBrush is SolidColorBrush solidBrush)
            {
                targetRectangle.Fill = solidBrush;
            }
        }
    }
}

Common Patterns

Pattern 1: Basic Palette with Theme and Standard Colors

<editors:SfColorPalette Name="colorPalette">
    <editors:SfColorPalette.PaletteColors>
        <editors:ColorPaletteModel ShowColorShades="True"/>
    </editors:SfColorPalette.PaletteColors>
    <editors:SfColorPalette.StandardColors>
        <editors:StandardPaletteModel ShowColorShades="True"/>
    </editors:SfColorPalette.StandardColors>
</editors:SfColorPalette>

Pattern 2: Active Palette (Theme Switching)

<!-- Show "Yellow" theme colors by default -->
<editors:SfColorPalette ActivePalette="Yellow" Name="colorPalette" />

// Switch theme programmatically
colorPalette.ActivePalette = ColorPaletteNames.Office;

Pattern 3: Custom Theme and Standard Colors

<editors:SfColorPalette Name="colorPalette">
    <editors:SfColorPalette.PaletteColors>
        <editors:ColorPaletteModel ShowColors="True" ShowColorShades="True" Header="Brand Colors">
            <editors:ColorPaletteModel.Colors>
                <editors:ColorCollection>
                    <editors:ColorModel Color="#FF1464A0" Tooltip="Brand Blue" />
                    <editors:ColorModel Color="#FF00A651" Tooltip="Brand Green" />
                    <editors:ColorModel Color="#FFFF6600" Tooltip="Brand Orange" />
                </editors:ColorCollection>
            </editors:ColorPaletteModel.Colors>
        </editors:ColorPaletteModel>
    </editors:SfColorPalette.PaletteColors>
</editors:SfColorPalette>

Pattern 4: Programmatic Color Selection

// Set selected color
colorPalette.SelectedBrush = new SolidColorBrush(Colors.Yellow);

// Set transparent/no color
colorPalette.SelectedBrush = new SolidColorBrush(Colors.Transparent);

// Read selected color
if (colorPalette.SelectedBrush is SolidColorBrush brush)
{
    var color = brush.Color;
}

Pattern 5: Enable All Options

<editors:SfColorPalette
    ShowMoreColorsButton="True"
    ShowNoColorButton="True"
    AutomaticBrush="Black"
    ShowDefaultColorButton="True"
    Name="colorPalette" />

Key Properties Reference

ColorPaletteModel / StandardPaletteModel Properties:

Key Events

Event Args Properties:

• OldBrush — Previously selected brush
• NewBrush — Newly selected brush

Common Use Cases

1. Document Editor — Font and highlight color selection (like MS Word color palette)
2. Theme Customizer — Let users pick from brand or theme colors
3. Drawing/Annotation Tool — Color picker for pen, highlighter, or shape fill
4. Form Design Tool — Background and text color selection for form elements
5. Dashboard Builder — Widget color assignment from a predefined palette

Next Steps

1. Start Simple: Begin with getting-started.md for basic setup
2. Theme Colors: Customize palette themes using theme-colors.md
3. Standard Colors: Configure standard color panel via standard-colors.md
4. More Colors: Add extended color dialog using more-color-dialog.md
5. Customize UI: Apply visual customizations from ui-customization.md
6. Optimize: Review best-practices.md for production-ready implementation

Note: This skill focuses on the Syncfusion WinUI Color Palette control (SfColorPalette). For gradient/spectrum-based color picking, refer to the syncfusion-winui-colorpicker skill.