Skip to content

PropertyFieldCollectionData control

This property field control gives you the ability to insert a list / collection data which can be used in your web part. For example: you want to specify multiple locations for showing a weather information.

The control allows you to specify multiple data types like: string, number, boolean, or dropdown.

PropertyFieldCollectionData

Code editor initial

The type of data you get returned depends on the fields you defined. For the example above, the data looks like this:

[
  {"Title":"Person","Lastname":"1","Age":"42","City":"helsinki","Sign":true},
  {"Title":"Person","Lastname":"2","Age":"42","City":"helsinki","Sign":true}
]

How to use this control in your solutions

  1. Check that you installed the @pnp/spfx-property-controls dependency. Check out The getting started page for more information about installing the dependency.
  2. Import the following modules to your component:
import { PropertyFieldCollectionData, CustomCollectionFieldType } from '@pnp/spfx-property-controls/lib/PropertyFieldCollectionData';
  1. Create a new property for your web part, for example:
export interface IPropertyControlsTestWebPartProps {
  collectionData: any[];
}
  1. Add the custom property control to the groupFields of the web part property pane configuration:
PropertyFieldCollectionData("collectionData", {
  key: "collectionData",
  label: "Collection data",
  panelHeader: "Collection data panel header",
  manageBtnLabel: "Manage collection data",
  value: this.properties.collectionData,
  fields: [
    {
      id: "Title",
      title: "Firstname",
      type: CustomCollectionFieldType.string,
      required: true
    },
    {
      id: "Lastname",
      title: "Lastname",
      type: CustomCollectionFieldType.string
    },
    {
      id: "Age",
      title: "Age",
      type: CustomCollectionFieldType.number,
      required: true
    },
    {
      id: "City",
      title: "Favorite city",
      type: CustomCollectionFieldType.dropdown,
      options: [
        {
          key: "antwerp",
          text: "Antwerp"
        },
        {
          key: "helsinki",
          text: "Helsinki"
        },
        {
          key: "montreal",
          text: "Montreal"
        }
      ],
      required: true
    },
    {
      id: "Sign",
      title: "Signed",
      type: CustomCollectionFieldType.boolean
    }
  ],
  disabled: false
})

Sample of custom field rendering

Here is an example of how you can render your own controls in the PropertyFieldCollectionData control:

{
  id: "customFieldId",
  title: "Custom Field",
  type: CustomCollectionFieldType.custom,
  onCustomRender: (field, value, onUpdate, item, itemId, onError) => {
    return (
      React.createElement("div", null,
        React.createElement("input", { key: itemId, value: value, onChange: (event: React.FormEvent<HTMLInputElement>) => {
          onUpdate(field.id, event.currentTarget.value);
          if (event.currentTarget.value === "error") {
            onError(field.id, "Value shouldn't be equal to error");
          } else {
            onError(field.id, "");
          }
        }}), " 🎉"
      )
    );
  }
}

Implementation

The PropertyFieldCollectionData control can be configured with the following properties:

Property Type Required Description Default Value
key string yes An unique key that indicates the identity of this control.
label string yes Property field label displayed on top.
panelHeader string yes Label to be used as the header in the panel.
panelDescription string no Property that allows you to specify a description in the collection panel.
manageBtnLabel string yes Label of the button to open the panel.
saveBtnLabel string no Label of the save button.
saveAndAddBtnLabel string yes Label of the save and add button.
cancelBtnLabel string yes Label of the cancel button.
fields ICustomCollectionField[] yes The fields to be used for the list of collection data.
value string yes The collection data value.
enableSorting boolean no Specify if you want to be able to sort the items in the collection. false
disabled boolean no Specify if the control is disabled. false
disableItemCreation boolean no Allows you to specify if user can create new items. false
disableItemDeletion boolean no Allows you to specify if users can delete already inserted items. false
panelClassName string no Allows you to specify a custom CSS class name for the collection data panel.
tableClassName string no Allows you to specify a custom CSS class name for the collection data table inside the panel.
panelProps IPanelProps no Allows you to pass in props of the panel such as type and size to control the underlying panel.

Interface ICustomCollectionField

Property Type Required Description
id string yes ID of the field.
title string yes Title of the field. This will be used for the label in the table.
type CustomCollectionFieldType yes Specifies the type of field to render.
disable (item: any) => boolean no Conditionally disable a field.
disableEdit boolean no Allows you to specify if a field is disabled for editing.
required boolean no Specify if the field is required.
options IDropdownOption[] | (fieldId: string, item: any) => IDropdownOption[] no Dropdown options. Only necessary when dropdown type is used. Options can be either a static array or a function that will calculate the values dynamically and can react to the current item.
onRenderOption IRenderFunction no Dropdown custom options render method. Only for the dropdown field type.
placeholder string no Placeholder text which will be used for the input field. If not provided the input title will be used.
defaultValue any no Specify a default value for the input field.
deferredValidationTime number no Field will start to validate after users stop typing for deferredValidationTime milliseconds. Default: 200ms.
onGetErrorMessage (value: any, index: number, crntItem: any): string | Promise no The method is used to get the validation error message and determine whether the input value is valid or not. It provides you the current row index and the item you are currently editing.
onCustomRender (field: ICustomCollectionField, value: any, onUpdate: (fieldId: string, value: any) => void, item: any, itemUniqueId: string, onCustomFieldValidation: (fieldId: string, errorMessage: string) => void) => JSX.Element no This property is only required if you are using the custom field type and it can be used to specify the custom rendering of your control in the collection data.
isVisible (field: ICustomCollectionField, items: any[]) => boolean no The method is used to toggle column visibility depending on current state of editing items
iconFieldRenderMode CollectionIconFieldRenderMode no Icon field render mode: text box or IconPicker

Enum CustomCollectionFieldType

Type Description
string Text field
number Number field
boolean Checkbox
dropdown Dropdown field. You will have to specify the options property when using this field type
fabricIcon Name of the Office UI Fabric icon
url URL field
custom This gives you control over the whole field rendering. Be sure to provide the onCustomRender method to render your control in the collection data.
color Color field

Type CollectionIconFieldRenderMode

export type CollectionIconFieldRenderMode = 'textbox' | 'picker';