Class SfColorPicker

Represents a ColorPicker component that provides an interactive interface for color selection with various modes and customization options.

Inheritance
System.Object
SfBaseComponent
SfColorPicker
Inherited Members
Namespace: Syncfusion.Blazor.Inputs
Assembly: Syncfusion.Blazor.dll
Syntax
public class SfColorPicker : SfBaseComponent
Remarks

The SfColorPicker component allows users to select colors through different interfaces like color palette, color picker, or both. It supports various color formats, opacity control, and can be customized with different themes and layouts.

Examples

Basic usage of ColorPicker component:

<SfColorPicker Value="#FF0000" Mode="ColorPickerMode.Both"></SfColorPicker>

The following code example showcases a basic ColorPicker component.

<SfColorPicker>
</SfColorPicker>

A basic ColorPicker component implementation.

<SfColorPicker Value="#ff0000" ValueChanged="OnColorChanged">
</SfColorPicker>

@code {
    private void OnColorChanged(ColorPickerEventArgs args)
    {
        // Handle color change
    }
}

A basic ColorPicker implementation.

<SfColorPicker Value="#ff0000" ValueChanged="@OnColorChanged">
</SfColorPicker>
@code {
    private void OnColorChanged(string color)
    {
        // Handle color change
    }
}

Constructors

SfColorPicker()

Declaration
public SfColorPicker()

Properties

ColorPickerEditContext

Gets or sets the edit context for the ColorPicker when used in Blazor forms.

Declaration
protected EditContext ColorPickerEditContext { get; set; }
Property Value
Type Description
Microsoft.AspNetCore.Components.Forms.EditContext

An Microsoft.AspNetCore.Components.Forms.EditContext instance for form validation. The default value is null.
Remarks

This cascading parameter is automatically provided by Blazor's EditForm component when the ColorPicker is placed within an EditForm. The EditContext enables the ColorPicker to participate in comprehensive form validation scenarios, including:

  • Automatic validation message display when validation rules are violated
  • Integration with validation attributes applied to model properties
  • Participation in form submission and validation workflows
  • Support for custom validation logic and error handling
The EditContext works in conjunction with ValueExpression to provide complete form integration capabilities.

ColorPickerParent

Parent component of ColorPicker.

Declaration
protected dynamic ColorPickerParent { get; set; }
Property Value
Type Description
System.Object

A dynamic reference to the parent component when ColorPicker is used within composite controls. The default value is null.
Remarks

This cascading parameter is automatically set when the ColorPicker is used within other Syncfusion components such as InPlaceEditor. It establishes the parent-child relationship and enables communication between the ColorPicker and its containing component. The dynamic type allows for flexible integration with various parent components without requiring explicit type constraints. This property is primarily used for internal component communication and is typically not accessed directly by application developers.

Columns

Gets or sets a value that indicates the columns to be rendered in palette mode.

Declaration
public double Columns { get; set; }
Property Value
Type Description
System.Double

A double value that specifies the number of columns in the color palette. The default value is 10.
Remarks

This property only applies when the Mode is set to Palette. The value determines the number of color tiles displayed horizontally in each row of the color palette. Setting this property helps organize the color palette layout for better user experience.

Created

Gets or sets an event callback that is raised when the SfColorPicker rendering is completed.

Declaration
public EventCallback<object> Created { get; set; }
Property Value
Type Description
Microsoft.AspNetCore.Components.EventCallback<System.Object>

An event callback function that receives an object parameter.
Remarks

This event is triggered once during the component lifecycle when the ColorPicker has been fully initialized and rendered to the DOM. It provides an opportunity to perform post-rendering operations such as:

  • Accessing DOM elements for custom styling or behavior
  • Setting up additional event handlers or observers
  • Initializing third-party integrations or plugins
  • Performing initial validation or state setup
The event is ideal for scenarios where you need to ensure the component is fully ready before executing dependent code.
Examples
<SfColorPicker Created="@OnCreated">
</SfColorPicker>
@code {
    private void OnCreated(object args)
    {
        // Perform post-rendering setup
        Console.WriteLine("ColorPicker has been created and rendered");
    }
}

CssClass

Gets or sets a value that indicates CSS class string to customize the appearance of color picker.

Declaration
public string CssClass { get; set; }
Property Value
Type Description
System.String

A string containing CSS class names separated by space to customize the appearance of color picker. The default value is null.
Remarks

You can apply multiple CSS classes by separating them with spaces. These classes will be added to the root element of the ColorPicker component, allowing for custom styling and theming. Custom CSS can be used to modify colors, spacing, borders, shadows, and other visual aspects of the component. When multiple classes are specified, they should be separated by spaces and will be applied in the order specified.

Disabled

Gets or sets a value that indicates whether to enable or disable the color picker.

Declaration
public bool Disabled { get; set; }
Property Value
Type Description
System.Boolean

true if the ColorPicker component is disabled; otherwise, false. The default value is false.
Remarks

When disabled, the ColorPicker cannot be interacted with and will appear in a disabled state. This prevents users from selecting colors or opening the color picker popup.

EnableOpacity

Gets or sets a value that indicates whether to enable or disable the opacity slider.

Declaration
public bool EnableOpacity { get; set; }
Property Value
Type Description
System.Boolean

true if the opacity slider is enabled; otherwise, false. The default value is true.
Remarks

When enabled, users can adjust the alpha/transparency value of the selected color using the opacity slider. The opacity slider allows values from 0 (completely transparent) to 100 (completely opaque). This property is applicable in both Picker and Palette modes.

EnablePersistence

Gets or sets a value that indicates whether to persist component's state between page reloads. When set to true, the Value property is persisted.

Declaration
public bool EnablePersistence { get; set; }
Property Value
Type Description
System.Boolean

true, if the component's state persistence is enabled. The default value is false.
Remarks

Component's Value property will be stored in browser local storage to persist component's state when page reloads. The persistence mechanism uses the browser's localStorage API to maintain the selected color value across browser sessions. This feature is particularly useful in scenarios where users frequently return to the same page and expect their color selections to be remembered. The persisted data is specific to the browser and domain, ensuring user privacy and data isolation.

EnableRtl

Gets or sets a value that indicates whether to enable or disable the right to left direction.

Declaration
public bool EnableRtl { get; set; }
Property Value
Type Description
System.Boolean

true, if the right to left direction is enabled for the component. The default value is false.
Remarks

When enabled, the ColorPicker component layout and text direction will be adjusted for right-to-left reading languages such as Arabic or Hebrew. This affects the positioning of elements, text alignment, and overall layout direction within the component. The RTL layout ensures proper user experience for applications targeting right-to-left language users.

Inline

Gets or sets a value that indicates whether to enable or disable the inline mode color picker.

Declaration
public bool Inline { get; set; }
Property Value
Type Description
System.Boolean

true if the color picker component is rendered as inline; otherwise, false. The default value is false.
Remarks

When set to true, the ColorPicker will be displayed inline on the page without requiring a trigger button. In inline mode, the color picker interface is always visible and does not appear in a popup. This is useful when you want the color selection interface to be permanently available to users.

Mode

Gets or sets a value that indicates the mode of color picker to be rendered.

Declaration
public ColorPickerMode Mode { get; set; }
Property Value
Type Description
ColorPickerMode

One of the ColorPickerMode enumeration. The default value is Picker
Remarks

The ColorPicker supports two distinct modes of operation:

  • Picker mode: Provides a continuous color spectrum with HSV (Hue, Saturation, Value) controls for precise color selection
  • Palette mode: Displays a grid of predefined colors for quick selection, with support for custom color groups and recent colors
The mode determines the user interface layout and interaction patterns. Picker mode is ideal for applications requiring precise color selection, while Palette mode is better suited for applications with predefined color schemes or brand-specific color sets. When ModeSwitcher is enabled, users can toggle between these modes at runtime.

ModeSwitched

Gets or sets an event callback that is raised when the SfColorPicker mode switch is performed.

Declaration
public EventCallback<ModeSwitchEventArgs> ModeSwitched { get; set; }
Property Value
Type Description
Microsoft.AspNetCore.Components.EventCallback<ModeSwitchEventArgs>

An event callback function that receives ModeSwitchEventArgs.
Remarks

You can access the Color Picker mode switch related values using ModeSwitchEventArgs. This event is triggered after the mode switch has been completed, allowing you to respond to changes between Picker and Palette modes.

ModeSwitcher

Gets or sets a value that indicates whether to enable or disable the mode switcher option.

Declaration
public bool ModeSwitcher { get; set; }
Property Value
Type Description
System.Boolean

true if the mode switcher option is enabled; otherwise, false. The default value is true.
Remarks

When enabled, users can switch between Picker and Palette modes using a toggle button in the ColorPicker interface. This allows for flexible color selection methods within the same component instance.

NoColor

Gets or sets a value that indicates whether to enable or disable the no color option.

Declaration
public bool NoColor { get; set; }
Property Value
Type Description
System.Boolean

true, if the no color option is enabled. The default value is false.
Remarks

The no color option is only available in palette mode and provides users with the ability to select "no color" or transparent as a valid choice. When enabled, an additional tile is displayed in the palette that represents the absence of color, often shown as a crossed-out or empty tile. This option is particularly useful in applications where color removal or transparency selection is a valid user choice, such as text editors, drawing applications, or design tools where users may want to remove color formatting.

OnClose

Gets or sets an event callback that is raised when the SfColorPicker popup is closing.

Declaration
public EventCallback<BeforeOpenCloseEventArgs> OnClose { get; set; }
Property Value
Type Description
Microsoft.AspNetCore.Components.EventCallback<BeforeOpenCloseEventArgs>

An event callback function that receives BeforeOpenCloseEventArgs.
Remarks

You can access the color picker popup related values using BeforeOpenCloseEventArgs. This event is triggered before the popup closes, allowing you to perform cleanup operations or validation. You can prevent the popup from closing by setting the Cancel property to true in the event args. This event is not applicable when Inline mode is enabled, as no popup is displayed.

OnModeSwitch

Gets or sets an event callback that is raised before the SfColorPicker mode switching is performed.

Declaration
public EventCallback<ModeSwitchEventArgs> OnModeSwitch { get; set; }
Property Value
Type Description
Microsoft.AspNetCore.Components.EventCallback<ModeSwitchEventArgs>

An event callback function that receives ModeSwitchEventArgs.
Remarks

You can access the Color Picker mode switch related values using ModeSwitchEventArgs. This event is triggered before switching between Picker and Palette modes, allowing you to perform validation or setup. You can prevent the mode switch by setting the Cancel property to true in the event args. This event is only applicable when ModeSwitcher is enabled.

OnOpen

Gets or sets an event callback that is raised when the SfColorPicker popup is opening.

Declaration
public EventCallback<BeforeOpenCloseEventArgs> OnOpen { get; set; }
Property Value
Type Description
Microsoft.AspNetCore.Components.EventCallback<BeforeOpenCloseEventArgs>

An event callback function that receives BeforeOpenCloseEventArgs.
Remarks

You can access the ColorPicker popup related values using BeforeOpenCloseEventArgs. This event is triggered before the popup opens, allowing you to perform validation or setup operations. You can prevent the popup from opening by setting the Cancel property to true in the event args. This event is not applicable when Inline mode is enabled, as no popup is displayed.

Examples
 
<SfColorPicker OnOpen="@OnOpen"> 
</SfColorPicker> 
@code { 
    private void OnOpen(BeforeOpenCloseEventArgs args) { 
        // Write your code here. 
    } 
}

OnTileRender

Gets or sets an event callback that is raised when the SfColorPicker tile rendering is completed.

Declaration
public EventCallback<PaletteTileEventArgs> OnTileRender { get; set; }
Property Value
Type Description
Microsoft.AspNetCore.Components.EventCallback<PaletteTileEventArgs>

An event callback function that receives PaletteTileEventArgs.
Remarks

You can customize the color picker tile rendering using PaletteTileEventArgs. This event is triggered for each color tile in palette mode, allowing you to modify tile appearance, add tooltips, or apply custom styling. Use the event args to access tile information such as color value, element reference, and position. This event is only applicable when the ColorPicker is in Palette mode.

Opened

Gets or sets an event callback that is raised when the SfColorPicker popup is opened.

Declaration
public EventCallback<OpenEventArgs> Opened { get; set; }
Property Value
Type Description
Microsoft.AspNetCore.Components.EventCallback<OpenEventArgs>

An event callback function that receives OpenEventArgs.
Remarks

You can access the ColorPicker popup related values using OpenEventArgs. This event is triggered after the popup has completely opened, unlike the OnOpen event which is triggered before opening.

Examples
 
<SfColorPicker Opened="@Opened"> 
</SfColorPicker> 
@code { 
    private void Opened(OpenEventArgs args) { 
        // Write your code here. 
    } 
}

PopupClosed

Gets or sets an event callback that is raised when the SfColorPicker popup is closed.

Declaration
public EventCallback<object> PopupClosed { get; set; }
Property Value
Type Description
Microsoft.AspNetCore.Components.EventCallback<System.Object>

An event callback function that receives an object parameter.
Remarks

This event is triggered after the popup has been completely closed and all closing animations have finished. It differs from the PopupClosed event in timing - while PopupClosed is triggered before closing (and can be cancelled), this event is triggered after the popup is fully closed and provides confirmation that the closing process is complete. This event is not applicable when Inline mode is enabled, as no popup is displayed in inline mode. Use this event for cleanup operations, state updates, or any logic that should execute after the popup is no longer visible.

Examples
<SfColorPicker PopupClosed="@OnPopupClosed">
</SfColorPicker>
@code {
    private void OnPopupClosed() {
        // Write your code here.
    }
}

PresetColors

Gets or sets a value that indicates the collection of custom color values that will be rendered as color picker element.

Declaration
public Dictionary<string, string[]> PresetColors { get; set; }
Property Value
Type Description
System.Collections.Generic.Dictionary<System.String, System.String[]>

A dictionary where keys represent group names and values are string arrays of color values. The default value is null.
Remarks

Preset colors option is only available in palette mode. The feature allows you to define custom color groups for quick access:

  • Dictionary keys serve as group headers (e.g., "Brand Colors", "Theme Colors", "Custom Palette")
  • Dictionary values contain arrays of hex color codes that will be rendered as clickable color tiles
  • Colors should be specified in valid hex format (#RGB, #RRGGBB, #ARGB, #AARRGGBB)
  • Multiple groups can be defined to organize colors by theme, brand, or purpose
This property enhances user experience by providing quick access to commonly used colors specific to your application or brand.

Selected

Gets or sets an event callback that is raised when the SfColorPicker palette or picker element is clicked.

Declaration
public EventCallback<ColorPickerEventArgs> Selected { get; set; }
Property Value
Type Description
Microsoft.AspNetCore.Components.EventCallback<ColorPickerEventArgs>

An event callback function that receives ColorPickerEventArgs.
Remarks

You can access the Color Picker selection related values using ColorPickerEventArgs. This event is triggered when a user interacts with color elements in either Picker or Palette mode:

  • In Picker mode: Triggered when clicking on the color area or saturation/hue controls
  • In Palette mode: Triggered when clicking on any color tile in the palette
The event provides access to both the current and previous color values, allowing you to track color selection changes.

ShowButtons

Gets or sets a value that indicates whether to enable or disable the apply/cancel buttons.

Declaration
public bool ShowButtons { get; set; }
Property Value
Type Description
System.Boolean

true if the apply/cancel buttons are enabled; otherwise, false. The default value is true.
Remarks

When enabled, users must click the "Apply" button to confirm their color selection and close the picker. When disabled, the color selection is applied immediately without requiring confirmation. The "Cancel" button allows users to discard their changes and revert to the previous color value.

ShowRecentColors

Gets or sets a value that indicates whether to show the recent colors section in the color picker interface.

Declaration
public bool ShowRecentColors { get; set; }
Property Value
Type Description
System.Boolean

true if the recent colors section is displayed; otherwise, false. The default value is false.
Remarks

This property is only applicable in palette mode and enhances user productivity by providing quick access to previously selected colors. When enabled, the ColorPicker maintains a dynamic list of recently used colors that appears as a separate section in the palette interface. The recent colors list is automatically updated each time a user selects a new color, maintaining the most recently used colors at the front. This feature is particularly beneficial in design applications where users frequently reuse colors within a project or session. The recent colors are session-specific and are not persisted across browser sessions unless EnablePersistence is also enabled.

Value

Gets or sets the color value for color picker. It should be specified as Hex code.

Declaration
public string Value { get; set; }
Property Value
Type Description
System.String

A string representing the color value in hexadecimal format. The default value is #008000ff.
Remarks

The color value should be specified in hexadecimal format with optional alpha channel. Supported formats include:

  • #RGB - Short format (e.g., #F0A)
  • #RRGGBB - Standard format (e.g., #FF00AA)
  • #ARGB - Short format with alpha (e.g., #8F0A)
  • #AARRGGBB - Full format with alpha (e.g., #88FF00AA)
When the value changes through user interaction or programmatic assignment, the ValueChanged event is triggered. The alpha component represents opacity where 00 is fully transparent and FF is fully opaque.

ValueChange

Gets or sets an event callback that is raised while changing the colors.

Declaration
public EventCallback<ColorPickerEventArgs> ValueChange { get; set; }
Property Value
Type Description
Microsoft.AspNetCore.Components.EventCallback<ColorPickerEventArgs>

An event callback function that receives ColorPickerEventArgs.
Remarks

The timing of this event depends on the ShowButtons property configuration:

  • When ShowButtons is false: Triggered immediately when colors are selected, providing real-time feedback
  • When ShowButtons is true: Triggered only when the Apply button is clicked, allowing users to preview before committing
Use ColorPickerEventArgs to access comprehensive information about the color change event, including:
  • Current selected color value in hexadecimal format
  • Previous color value for comparison purposes
  • Event source information and interaction context
This event is crucial for implementing custom validation logic, real-time previews, and complex color management workflows.
Examples
<SfColorPicker ValueChange="@OnValueChange">
</SfColorPicker>
@code {
    private void OnValueChange(ColorPickerEventArgs args)
    {
        string currentColor = args.CurrentValue.Hex;
        string previousColor = args.PreviousValue.Hex;
        // Handle color change logic
    }
}

ValueChanged

Gets or sets an event callback that is raised when the SfColorPicker color value changed.

Declaration
public EventCallback<string> ValueChanged { get; set; }
Property Value
Type Description
Microsoft.AspNetCore.Components.EventCallback<System.String>

An event callback function that receives the new color value as a string parameter.
Remarks

This event is essential for implementing two-way data binding with the ColorPicker component. It is triggered whenever the color value changes, either through user interaction or programmatic assignment. The event provides the new color value as a hexadecimal string, enabling parent components to respond to color changes immediately. When used with @bind-Value, this event callback is automatically handled by Blazor's data binding framework.

Examples
<SfColorPicker Value="@selectedColor" ValueChanged="@OnColorValueChanged">
</SfColorPicker>
@code {
    private string selectedColor = "#ff0000";

    private void OnColorValueChanged(string newColor)
    {
        selectedColor = newColor;
        // Perform additional logic with the new color
    }
}

ValueExpression

Gets or sets the expression for defining the value of the bound field.

Declaration
public Expression<Func<string>> ValueExpression { get; set; }
Property Value
Type Description
System.Linq.Expressions.Expression<System.Func<System.String>>

An expression that identifies the bound value. The default value is null.
Remarks

This property is essential for Blazor's two-way data binding and form validation infrastructure. It should contain a lambda expression that identifies the property being bound to the ColorPicker component. When used with @bind-Value, Blazor automatically sets this property to enable proper data binding and validation. The expression is used by validation attributes and the EditContext to identify which field is being validated and to display appropriate validation messages. This property works in conjunction with ColorPickerEditContext to provide comprehensive form integration.

Examples
<EditForm Model="@model">
    <SfColorPicker @bind-Value="@model.BackgroundColor" 
                   ValueExpression="@(() => model.BackgroundColor)">
    </SfColorPicker>
</EditForm>

Methods

BuildRenderTree(RenderTreeBuilder)

Declaration
protected override void BuildRenderTree(RenderTreeBuilder __builder)
Parameters
Type Name Description
Microsoft.AspNetCore.Components.Rendering.RenderTreeBuilder __builder

FocusAsync()

Asynchronously sets focus to the ColorPicker component.

Declaration
public Task FocusAsync()
Returns
Type Description
System.Threading.Tasks.Task

A System.Threading.Tasks.Task that represents the asynchronous focus operation. The task completes when focus has been successfully set.
Remarks

This method programmatically sets focus to the ColorPicker component. In inline mode, focus is set to the color picker interface directly, allowing immediate keyboard interaction with color selection controls. In popup mode, focus is set to the trigger button that opens the ColorPicker popup, enabling keyboard navigation and popup activation. The focus operation is performed asynchronously to ensure proper DOM manipulation and browser focus handling.

Examples
// Set focus to the ColorPicker component
await colorPicker.FocusAsync();

GetValue(String, ColorValueType)

Gets the color value in the specified format type.

Declaration
public string GetValue(string value = null, ColorValueType type)
Parameters
Type Name Description
System.String value

The color value to convert. If null, uses the current Value property.
ColorValueType type

The target color format type for conversion. The default is Hex.
Returns
Type Description
System.String

A string representing the color value converted to the specified format type, or null if conversion fails.
Remarks

This method supports conversion between various color formats including:

  • Hex: Hexadecimal format without alpha (e.g., #FF0000)
  • Hexa: Hexadecimal format with alpha (e.g., #FF0000FF)
  • Rgb: RGB format without alpha (e.g., rgb(255, 0, 0))
  • Rgba: RGB format with alpha (e.g., rgba(255, 0, 0, 1))
  • Hsv: HSV format without alpha (e.g., hsv(0, 100%, 100%))
  • Hsva: HSV format with alpha (e.g., hsva(0, 100%, 100%, 1))
  • Opacity: Returns only the opacity value as a decimal number
The input value can be in any supported format and will be automatically detected and converted. If conversion fails due to invalid input format or processing errors, the method returns null.
Examples
// Convert current value to RGB format
string rgbValue = colorPicker.GetValue(null, ColorValueType.Rgb);

// Convert a hex value to RGBA format
string rgbaValue = colorPicker.GetValue("#FF0000", ColorValueType.Rgba);

// Get opacity value from an RGBA color
string opacity = colorPicker.GetValue("rgba(255, 0, 0, 0.5)", ColorValueType.Opacity);
Exceptions
Type Condition
System.Exception

Thrown when an error occurs during color format conversion or processing.

OnAfterRenderAsync(Boolean)

Executes logic after the component has been rendered to the DOM.

Declaration
protected override Task OnAfterRenderAsync(bool firstRender)
Parameters
Type Name Description
System.Boolean firstRender

A System.Boolean value indicating whether this is the first time the component is being rendered.
Returns
Type Description
System.Threading.Tasks.Task

A System.Threading.Tasks.Task representing the asynchronous post-render operation.
Overrides
Remarks

This method is called after each render cycle. On the first render, it triggers the Created event callback if one has been provided. This allows consumers to perform actions once the component has been fully initialized and rendered.

OnInitializedAsync()

Initializes the ColorPicker component asynchronously when the component is first created.

Declaration
protected override Task OnInitializedAsync()
Returns
Type Description
System.Threading.Tasks.Task

A System.Threading.Tasks.Task representing the asynchronous initialization operation.
Overrides
Remarks

This method is called once during the component's lifecycle when it is first initialized. It sets up the initial state, script modules, property values, and handles special cases for In-place Editor component integration. The method also calls the base initialization and performs component-specific initialization tasks.

OnParametersSetAsync()

Handles parameter changes and updates the component state asynchronously.

Declaration
protected override Task OnParametersSetAsync()
Returns
Type Description
System.Threading.Tasks.Task

A System.Threading.Tasks.Task representing the asynchronous parameter update operation.
Remarks

This method is called whenever component parameters are set or changed. It manages property change notifications, value updates, localization, and triggers appropriate state changes based on which properties have been modified. The method ensures proper two-way data binding and component state synchronization.

Toggle()

Shows or hides the ColorPicker popup based on its current state.

Declaration
public void Toggle()
Remarks

This method toggles the visibility of the ColorPicker popup. If the popup is currently closed, it will be opened. If the popup is currently open, it will be closed. This method is only applicable when the ColorPicker is not in inline mode. In inline mode, this method has no effect since the ColorPicker is always visible. The toggle operation is performed immediately without any animation delay.

Examples
// Toggle the ColorPicker popup visibility
colorPicker.Toggle();