Class ColorField

A field that allows users to select and display colors.

Inheritance
object
CallbackEventHandler
Focusable
VisualElement
BaseVisualElement
ExVisualElement
ColorField
Implements
Inherited Members
VisualElement.Focus()
VisualElement.Overlaps(Rect)
VisualElement.ToString()
VisualElement.TryGetBinding(BindingId, out Binding)
VisualElement.TryGetDataSourceContext(BindingId, out DataSourceContext)
VisualElement.TryGetLastBindingToUIResult(in BindingId, out BindingResult)
VisualElement.TryGetLastBindingToSourceResult(in BindingId, out BindingResult)
VisualElement.GetFirstOfType<T>()
VisualElement.GetFirstAncestorOfType<T>()
VisualElement.canGrabFocus
VisualElement.focusController
VisualElement.cacheAsBitmap
CallbackEventHandler.RegisterCallback<TEventType>(EventCallback<TEventType>, TrickleDown)
CallbackEventHandler.RegisterCallbackOnce<TEventType>(EventCallback<TEventType>, TrickleDown)
CallbackEventHandler.RegisterCallback<TEventType, TUserArgsType>(EventCallback<TEventType, TUserArgsType>, TUserArgsType, TrickleDown)
CallbackEventHandler.RegisterCallbackOnce<TEventType, TUserArgsType>(EventCallback<TEventType, TUserArgsType>, TUserArgsType, TrickleDown)
CallbackEventHandler.RegisterCallback<TEventType>(EventCallback<TEventType>, CallbackOptions)
CallbackEventHandler.RegisterCallback<TEventType, TUserArgsType>(EventCallback<TEventType, TUserArgsType>, TUserArgsType, CallbackOptions)
CallbackEventHandler.UnregisterCallback<TEventType>(EventCallback<TEventType>, TrickleDown)
CallbackEventHandler.UnregisterCallback<TEventType>(EventCallback<TEventType>, CallbackOptions)
CallbackEventHandler.UnregisterCallback<TEventType, TUserArgsType>(EventCallback<TEventType, TUserArgsType>, TrickleDown)
CallbackEventHandler.UnregisterCallback<TEventType, TUserArgsType>(EventCallback<TEventType, TUserArgsType>, CallbackOptions)
CallbackEventHandler.NotifyPropertyChanged(in BindingId)
Namespace: Unity.AppUI.UI
Assembly: Unity.AppUI.dll
Syntax
[UxmlElement]
public class ColorField : ExVisualElement, IEventHandler, IResolvedStyle, ITransform, ITransitionAnimations, IExperimentalFeatures, IVisualElementScheduler, IContextOverrideElement, IAdditionalDataHolder, IInputElement<Color>, IValidatableElement<Color>, INotifyValueChanging<Color>, INotifyValueChanged<Color>, ISizeableElement, IPressable
Remarks

The ColorField component provides an interface for users to view, select, and modify colors. It displays the current color value through a color swatch and optionally shows the color's hex value. When clicked, it opens a color picker that allows detailed color selection.

The component supports two different color picker types: the default AppUI color picker and Unity's editor color picker. The color picker provides multiple ways to select colors including a color wheel, RGB sliders, HSV sliders, and hex input.

Key features:

  • Color visualization through a swatch
  • Optional text display of color value
  • Support for alpha channel
  • HDR color support
  • Multiple size variants
  • Inline or popover color picker
Examples

Basic ColorField with default settings. Creates a ColorField with medium size and all default settings.

<ColorField />

ColorField with custom configuration. Creates a large ColorField with medium swatch, alpha support, HDR colors, and inline picker.

<ColorField
    size="L"
    swatch-size="M"
    show-alpha="true"
    hdr="true"
    inline-picker="true"
    show-text="true" />

Minimal ColorField showing only the swatch. Creates a minimal ColorField showing only the color swatch.

<ColorField
    swatch-only="true"
    size="S"
    show-text="false" />

Code example showing how to handle color changes. Demonstrates how to create a ColorField, register for value changes, and set its value programmatically.

var colorField = new ColorField();
colorField.RegisterValueChangedCallback(evt => {
    Debug.Log($"Color changed from {evt.previousValue} to {evt.newValue}");
});
colorField.value = Color.blue;

Constructors

ColorField()

Default constructor.

Declaration
public ColorField()

Fields

colorPickerIconUssClassName

The ColorField color picker icon styling class.

Declaration
public const string colorPickerIconUssClassName = "appui-colorfield__color-picker-icon"
Field Value
Type Description
string

colorSwatchUssClassName

The ColorField color swatch styling class.

Declaration
public const string colorSwatchUssClassName = "appui-colorfield__color-swatch"
Field Value
Type Description
string

inlinePickerOpenedUssClassName

The ColorField inline picker opened styling class.

Declaration
public const string inlinePickerOpenedUssClassName = "appui-colorfield--inline-picker-opened"
Field Value
Type Description
string

labelUssClassName

The ColorField label styling class.

Declaration
public const string labelUssClassName = "appui-colorfield__label"
Field Value
Type Description
string

showTextUssClassName

The ColorField showText styling class.

Declaration
public const string showTextUssClassName = "appui-colorfield--show-text"
Field Value
Type Description
string

sizeUssClassName

The ColorField size styling class.

Declaration
public const string sizeUssClassName = "appui-colorfield--size-"
Field Value
Type Description
string

swatchOnlyUssClassName

The ColorField swatch only styling class.

Declaration
public const string swatchOnlyUssClassName = "appui-colorfield--swatch-only"
Field Value
Type Description
string

ussClassName

The ColorField main styling class.

Declaration
public const string ussClassName = "appui-colorfield"
Field Value
Type Description
string

Properties

clickable

Clickable Manipulator for this ColorField.

Declaration
[CreateProperty]
public Pressable clickable { get; set; }
Property Value
Type Description
Pressable

colorPickerType

The ColorField color picker type.

Declaration
[CreateProperty]
[UxmlAttribute]
public ColorPickerType colorPickerType { get; set; }
Property Value
Type Description
ColorPickerType

contentContainer

The content container of this ColorField. This is null for ColorField.

Declaration
public override VisualElement contentContainer { get; }
Property Value
Type Description
VisualElement
Overrides

customPicker

The custom color picker for the ColorField.

Declaration
[CreateProperty]
public ICustomColorFieldPicker customPicker { get; set; }
Property Value
Type Description
ICustomColorFieldPicker
Examples
// Example implementation of a custom color picker
public class CustomColorPicker : ICustomColorFieldPicker
{
    private VisualElement m_PickerWindow;
    private Action<Color> m_OnValueChanging;
    private ColorField m_Owner;
    private Color m_InitialColor;

    public void Show(ColorField owner, Action<Color> onValueChanging, Color initialColor, bool showAlpha, bool hdr)
    {
        m_Owner = owner;
        m_OnValueChanging = onValueChanging;
        m_InitialColor = initialColor;

        // Create custom picker UI
        m_PickerWindow = new VisualElement { name = "custom-picker" };

        // Setup picker with callbacks
        var picker = new MyCustomPickerUI(initialColor, showAlpha, hdr);

        picker.onColorChanged += (color) =>
        {
            // Send ChangingEvent while picker is still open
            m_OnValueChanging?.Invoke(color);
        };

        picker.onColorAccepted += (color) =>
        {
            // Send final ChangeEvent like the default implementation
            using var evt = ChangeEvent<Color>.GetPooled(m_InitialColor, color);
            evt.target = m_Owner;
            m_Owner.SetValueWithoutNotify(color);
            m_Owner.SendEvent(evt);
            ClosePickerWindow();
        };

        picker.onCanceled += () =>
        {
            // Revert to initial color
            m_OnValueChanging?.Invoke(m_InitialColor);
            ClosePickerWindow();
        };

        m_PickerWindow.Add(picker);
        owner.rootVisualElement.Add(m_PickerWindow);
    }

    private void ClosePickerWindow()
    {
        m_PickerWindow?.RemoveFromHierarchy();
        m_OnValueChanging = null;
        m_Owner?.Focus();
    }
}

// Usage:
var colorField = new ColorField();
colorField.customPicker = new CustomColorPicker();

hdr

Whether to show the HDR colors in the ColorPicker.

Declaration
[CreateProperty]
[UxmlAttribute]
public bool hdr { get; set; }
Property Value
Type Description
bool

inlinePicker

The ColorPicker position relative to the ColorField. When this is true, the ColorPicker will be inlined instead of being displayed in a Popover.

Declaration
[CreateProperty]
[UxmlAttribute]
public bool inlinePicker { get; set; }
Property Value
Type Description
bool

invalid

The ColorField invalid state.

Declaration
[CreateProperty]
[UxmlAttribute]
public bool invalid { get; set; }
Property Value
Type Description
bool

showAlpha

Whether to show the alpha channel in the ColorPicker.

Declaration
[CreateProperty]
[UxmlAttribute]
public bool showAlpha { get; set; }
Property Value
Type Description
bool

showText

Whether to show the text label for the ColorField.

Declaration
[CreateProperty]
[UxmlAttribute]
public bool showText { get; set; }
Property Value
Type Description
bool

size

The ColorField size.

Declaration
[CreateProperty]
[UxmlAttribute]
public Size size { get; set; }
Property Value
Type Description
Size

swatchOnly

The ColorField type. When this is true, the ColorField will only show the swatch.

Declaration
[CreateProperty]
[UxmlAttribute]
public bool swatchOnly { get; set; }
Property Value
Type Description
bool

swatchSize

The ColorField swatch size.

Declaration
[CreateProperty]
[UxmlAttribute]
public Size swatchSize { get; set; }
Property Value
Type Description
Size

validateValue

The ColorField validation function.

Declaration
[CreateProperty]
public Func<Color, bool> validateValue { get; set; }
Property Value
Type Description
Func<Color, bool>

value

The ColorField value.

Declaration
[CreateProperty]
[UxmlAttribute]
public Color value { get; set; }
Property Value
Type Description
Color

Methods

GetSizeUssClassName(Size)

Declaration
public static string GetSizeUssClassName(Size enumValue)
Parameters
Type Name Description
Size enumValue
Returns
Type Description
string

SetValueWithoutNotify(Color)

Sets the ColorField value without notifying the ColorField.

Declaration
public void SetValueWithoutNotify(Color newValue)
Parameters
Type Name Description
Color newValue

The new ColorField value.

Implements

Extension Methods