Today I want to introduce you the useful PnP reusable property pane controls, this package contains a lot of useful controls that can be used in any web part property pane.

With this article I want to show you how to use the PropertyFieldColorPicker control to enable the selection of a specific color in the property pane.

To demonstrate the various capabilities of the control I’ve created a sample solution which you can find here. The sample solution contains a simple web part that shows the colors selected with the PropertyFieldColorPicker control from the web part property pane. Here you can see the initial result where no color has been yet selected:

Following, the result when the colors are selected:

Ok, now that you have an idea of what we’re talking about, I will show you the various instances of the control, starting with the screenshots and then I will explain each one of those:

Those were all the instances of the control that are defined in the property pane of the web part.

Basic instance

Starting with the explanations let’s talk about the basic instance. This is used to demonstrate the minimal configuration for the control, by default the control will display a rectangle with the selected color and an icon on the right that allow the user to open the color picker panel:

Once clicked on the icon the color picker panel will open and will allow the selection of the color by either selecting it from the spectrum or by specifying the hexadecimal or decimal values:

Customizable picker

After the basic instance there are four toggles, those are used to change the settings of the following customizable picker instance.

Here you can see the customizable picker instance once the user clicked on the icon, this is just for reference to compare with the other screenshots of the same control instance:

With the show preview toggle turned on a square with the selected color will be added in the color picker panel:

It’s possible to disable a color picker, if it’s defined as an inline picker the icon will be disabled and will prevent the user from opening the panel, if the style of the picker is the full one all the controls will be disabled.

This is the control picker disabled with the inline style:

This is the control picker disabled with the full style:

Another toggle setting shows the ability to hide a color picker control, as you can see in the following screenshot the customizable picker control is hidden from the UI leaving space for the following control:

The last toggle enables the change of the color picker style from inline to full, here you can see what’s the full style like:

Other instances

Proceeding with the instances the next in line is the instance that shows the control without the alpha slider:

The icon name instance shows the possibility to change the displayed icon for the inline style:

The last two instances are more interesting from the code point of view but to be clear those are:

As object value : this shows how you can change the control value from a string to an object.
On property change : this will show how to handle the value change event, in this instance the #ffffff and #000000 values are not selectable, instead an alert will be shown to notify the user.

Show me the code

To use the PnP property controls first you need to install the package:

npm install @pnp/spfx-property-controls --save --save-exact

After the installation of the package you can proceed with the following explanations for the PropertyFieldColorPicker _ _control.

To use the control you have to import it in the web part file with the following import statement:

import {
    PropertyFieldColorPicker,
    PropertyFieldColorPickerStyle,
} from "@pnp/spfx-property-controls/lib/PropertyFieldColorPicker";

After the import statement you will have to declare the control instances in the getPropertyPaneConfiguration method but before doing so I will briefly explain what are the properties that will store the values. In the web part properties I have defined the following:

export interface IColorPickerSampleWebPartProps {
    baseValue: string;
    noAlphaSliderValue: string;
    fullPickerValue: string;
    disabled: boolean;
    hidden: boolean;
    showPreview: boolean;
    showFull: boolean;
    customizablePickerValue: string;
    iconNameValue: string;
    asObjectValue: any;
    onPropertyChangeValue: string;
}

Now that you have an idea of the properties that we will use here are the control instances and the corresponding focused properties that are defined in the getPropertyPaneConfiguration method.

Basic usage

This instance is the one with the minimal configuration and the default behavior:

PropertyFieldColorPicker("baseValue", {
  label: strings.BasicSelectColorLabel,
  selectedColor: this.properties.baseValue,
  onPropertyChange: this.onPropertyPaneFieldChanged,
  properties: this.properties,
  key: "basicUsage", }),

The first argument, the "baseValue" one, is the name of the web part property that the control instance will handle.

The basic properties of the control are, as you can see, the following:

label: is the displayed label of the property control.
selectedColor: this is not really a required one but it’s useful to set the selected color in the picker control.
onPropertyChange: this method is used to handle the color change, by default you can bind the web part onPropertyPaneFieldChanged method to automatically handle the change.
properties: the web part properties, used to update the property value.
key: the identifier of the control instance.

Customizable color picker

This instance shows a few possible customization using the toggles to dinamically show the changes in the UI.

The control is defined as following:

PropertyFieldColorPicker("customizablePickerValue", {
  label: strings.CustomizablePickerLabel,
  selectedColor: this.properties.customizablePickerValue,
  onPropertyChange: this.onPropertyPaneFieldChanged,
  properties: this.properties,
  key: "togglesPicker",
  isHidden: this.properties.hidden,
  disabled: this.properties.disabled,
  showPreview: this.properties.showPreview,
  style:
    this.properties.showFull === true
    ? PropertyFieldColorPickerStyle.Full
    : PropertyFieldColorPickerStyle.Inline, }),

Aside the properties explained before in the basic usage there are other useful properties, in detail those are:

isHidden: this property accepts a boolean value and define if the control instance is shown or hidden.
disabled: is a boolean value that allows the control instance to be disabled or enabled.
showPreview: this boolean property allows the display of a square with the selected color beside the color picker slider.
style: this accept an enumerable value from the PropertyFieldColorPickerStyle enum, the currently available values are:
- Inline: this is the default value for the style property and display a rectangle with the selected color and an icon on the right to open the color picker panel.
- Full: this will display only the color picker panel without the ability to open or close it.

No alpha slider

This instance demonstrate how you can enable or disable the alpha slider using the alphaSliderHidden property, if the property is set to true the alpha slider will not be shown in the UI, this control instance is defined as following:

PropertyFieldColorPicker("noAlphaSliderValue", {
  label: strings.NoAlphaSliderColorLabel,
  selectedColor: this.properties.noAlphaSliderValue,
  onPropertyChange: this.onPropertyPaneFieldChanged,
  properties: this.properties,
  alphaSliderHidden: true,
  key: "noAlphaSlider",
}),

Icon name

Using the default control style, the Inline one, you can customize the icon that the user can click to open the control picker panel, to do so you can specify the Fluent UI icon name that you want to display setting it to the iconName property. In the sample I’ve defined the Eyedropper icon name:

PropertyFieldColorPicker("iconNameValue", {
  label: strings.IconNameSelectColorLabel,
  selectedColor: this.properties.iconNameValue,
  onPropertyChange: this.onPropertyPaneFieldChanged,
  properties: this.properties,
  iconName: "Eyedropper",
  key: "noPreviewUsage",
}),

Value as object

It’s possible to retrieve an object instead of the color string value, to configure the control instance to do so you have only to set the valueAsObject property to true. In the sample I’ve displayed the old and new value in the console log, you can see the code here:

PropertyFieldColorPicker("asObjectValue", {
  label: strings.AsObjectValueSelectColorLabel,
  selectedColor: this.properties.asObjectValue,
  onPropertyChange: (
    propertyPath: string,
    oldValue: any,
    newValue: any
  ) => {
    console.log(oldValue);
    console.log(newValue);
    this.onPropertyPaneFieldChanged(
      propertyPath,
      oldValue,
      newValue
    );
  },
  properties: this.properties,
  valueAsObject: true,
  key: "asObjectValue",
}),

For reference, the object structure is the following:

{
    "a": 100,
    "b": 247,
    "g": 99,
    "h": 230,
    "hex": "4563f7",
    "r": 69,
    "s": 72,
    "str": "#4563f7",
    "v": 97,
    "t": 0
}

If you want an explanation for the properties of the object you can have a look at the official documentation here.

OnPropertyChange

In this instance I want to show how you can perform custom operations before effectively change the property value, this can be achieved specifying a custom method and setting it to the onPropertyChange property, in the sample I’ve defined the control instance as following:

PropertyFieldColorPicker("onPropertyChangeValue", {
  label: strings.OnPropertyChangeSelectColorLabel,
  selectedColor: this.properties.onPropertyChangeValue,
  onPropertyChange: (
    propertyPath: string,
    oldValue: any,
    newValue: any
  ) => {
    if (newValue === "#ffffff" 
        || newValue === "#000000") {
    alert(strings.CannotSelectThisColorErrorMessage);
    return;
    }
    this.onPropertyPaneFieldChanged(
      propertyPath,
      oldValue,
      newValue
    );
  },
  properties: this.properties,
  key: "onPropertyChange",
}),

In this code the user is not allowed to select the #ffffff or #000000 colors, if it does so an alert will be shown to notify the user of the restriction.

Wrap up

If you need a custom control to handle a property pane value it’s best that you have a look at the already existing PnP reusable react property controls because probably there’s already something for what you need to achieve!

The color picker control is pretty useful in term of allowing UI customization from the property pane and is really convenient because is a ready to use control!

Hope this helps!

Overview of the Color Picker control from the PnP Property Controls