Example - Color selector UI form component

This page provides a step-by-step example demonstrating the process of creating, configuring, and registering a UI form component in the system. The component renders a color selector and returns the selected color in the hexadecimal format.

For example, when used in Page Builder widget properties, the component can enable users to set the color of some part or element rendered by the widget. See the following screenshot for an illustration.

Color selector in widget properties

If you have not yet done so, prepare your development environment according to Prepare your environment for admin development. UI form components consist of both back-end and front-end code, so you’ll need to prepare a custom JavaScript module as well.

Custom code best practices

We recommend separating admin UI customizations into a dedicated class library project. Using separate assemblies keeps the code intended for the admin UI separate from your site implementation. It also provides a convenient place to embed compiled JS modules with client code and simplifies certain advanced deployment scenarios.

After your environment is set up, implement the component’s back-end definition.

ColorSelectorFormComponent.cs



using System.Threading.Tasks;

using Kentico.Xperience.Admin.Base.FormAnnotations;
using Kentico.Xperience.Admin.Base.Forms;

namespace Acme.Web.Admin.UIFormComponents.ColorSelector
{
    [ComponentAttribute(typeof(ColorSelectorComponentAttribute))]
    public class ColorSelectorFormComponent : FormComponent<ColorSelectorFormComponentClientProperties, string>
    {
        // The name of client React component to invoke, without the 'FormComponent' suffix
        public override string ClientComponentName => "@acme/web-admin/ColorSelector";

        protected override Task ConfigureClientProperties(ColorSelectorFormComponentClientProperties clientProperties)
        {
            base.ConfigureClientProperties(clientProperties);

            // Sets the default value of the component - white preselected
            clientProperties.Value = "#FFFFFF";

            return Task.CompletedTask;
        }
    }

    // Client properties class
    public class ColorSelectorFormComponentClientProperties : FormComponentClientProperties<string>
    {
    }
}

Next, define the editing component attribute used for annotating other properties.

ColorSelectorComponentAttribute.cs



using Kentico.Xperience.Admin.Base.FormAnnotations;

// The component doesn't define any custom configuration properties.
// The default attribute definition is therefore sufficient.
public class ColorSelectorComponentAttribute : FormComponentAttribute
{
}

Finally, write the React component that renders the user interface. The component makes use of a color picker from the react-colorful library.

package.json



"dependencies": {
    ...
    "react-colorful": "^5.x.x"
  },

Color selector component front-end (ColorSelectorFormComponent.tsx)



import React, { useState } from 'react';

// Imports a color selector component from react-colorful
import { HexColorPicker } from "react-colorful";

import { FormComponentProps } from '@kentico/xperience-admin-base';
import { FormItemWrapper } from '@kentico/xperience-admin-components';

export const ColorSelectorFormComponent = (props: FormComponentProps) => {

    const handleOnChange = (value: string) => {
        // If 'onChange' is undefined, do nothing
        if (props.onChange) {
            // Passes the new user input to a parent component where all field values are maintained.
            // 'value' emitted by the color picker's onChange event stores the most up to date input of the component.
            props.onChange(value);
        }
    }; 

    // Renders the color selector and ensures propagation of the selected value
    return <FormItemWrapper
                label={props.label}
                explanationText={props.explanationText}
                invalid={props.invalid}
                validationMessage={props.validationMessage}
                markAsRequired={props.required}
                labelIcon={props.tooltip ? 'xp-i-circle' : undefined}
                labelIconTooltip={props.tooltip}>
                    <HexColorPicker color={props.value} onChange={handleOnChange} />
            </FormItemWrapper>;
};

To make the component available from the admin UI, it must be exported from the client module’s entry.tsx:

entry.tsx


// Export the full path to the component file
export * from './form-components/ColorSelectorFormComponent';

The UI form component is ready for use in builder component dialogs and model-driven UI forms. To enable usage in the field editor, register the component using RegisterFormComponent.

Form component registration



[assembly: RegisterFormComponent("Acme.UIFormComponents.ColorSelector", 
                                 typeof(ColorSelectorFormComponent),
                                 "Color selector")]