Discover the PropertyGridField control from the PnP property controls

Introduction

Proceeding our dive into the PnP reusable property pane controls I want to cover the PropertyGridField control.

The PnP reusable property pane controls is a package that contains a lot of useful controls that can be used in any SharePoint Framework web part’s property pane, if you want to know more about this you can check out the official site here.

To demonstrate the various capabilities of the control I’ve created a sample solution which you can find here.

Visual appearance

The sample solution consists of a web part that shows the selection made in the property pane and the PropertyGridField control instantiated in the property pane.

The web part is a pretty minimalistic one with just a title and the selected item(s):

The property pane, on the other hand, consist of a group of toggle controls and another group containing the instance of the PropertyGridField control:

The toggles are used to quickly enable the display of the PropertyGridField control or to enable/disable the multi selection.

When the control is hidden it won’t display anything as you can see in the following screenshot:

By default, the control enables a single row selection in the grid:

When selecting one or more items in the grid the web part will show the title of the select item(s):

Enabling the multi selection will change the radio buttons into check boxes:

This will render as an unordered list in the web part:

One other useful feature of the PropertyGridField control is the built in sorting. In the previous screenshot the sort was on the Title column in an ascending fashion, just by clicking on the column header it will change the sorting to a descending fashion:

Now that we have a minimal understanding of what the control can do, let’s see how to use it from a code perspective.

Show me the code

Prerequisites

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 PropertyGridField control.

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

import {
  PropertyFieldGrid
} from "@pnp/spfx-property-controls/lib/propertyFields/propertyFieldGrid";

Now that we have the SharePoint Framework solution ready let’s cover how to use the control.

Using the control

Once that the control is imported you can use it in the property pane. The code from the sample solution is the following:

PropertyFieldGrid("items", {
  multiSelect: this.properties.enableMultiSelection ?? false,
  items: this._getItems(),
  label: strings.GridFieldLabel,
  key: "gridFieldId",
  defaultSelectedItems: this.properties.items,
  maxHeight: 500,
  styles: { padding: 2 },
  isVisible: this.properties.showGrid ?? true,
  column1Label: "Title",
  column2Label: "Content",
  onSelected: (item: IItem[]) => {
    console.log(item);
  },
})

Here you can see that the isVisible and multiSelect properties are bound to the web part properties.

Now let’s quickly cover what are the other properties:

• items: will be populated by the items that will be shown in the grid, I will cover shortly how the items are constructed.
• defaultSelectedItems: this will contain the items that are already selected when the control renders.
• onSelected: offers the ability to perform some custom operation when one or more items are selected.

Aside of the previous properties, there are also the column1Label and column2Label which needs a small explanation. Before explaining those let’s briefly cover what’s the type of items that can be bound to the control. Those items will have to be of type IItem which is composed as follows:

export interface IItem {
    key: string;
    icon: string | JSX.Element;
    title: string | JSX.Element;
    description: string | JSX.Element;
}

The IItem interface can be imported as following:

import { IItem } from "@pnp/spfx-property-controls/lib/propertyFields/propertyFieldGrid/grid/IItem";

Now that we know what are the available properties for the items let’s see what the grid columns label does. The two properties column1Label and column2Label are the only two columns available in the grid and handle a couple of properties from the IItem interface:

• column1Label: is the label that will correspond to the title property of the IItem.
• column2Label: allows to specify which is the label of the second column. This column corresponds to the description property of the IItem interface.

You can change the label of the columns but underneath they will always use the value of the title and description properties.

Just for the sake of completeness, the sample items that are used in the solution are retrieved using the _getItems method and the code of the method is the following:

private _getItems(): IItem[] {
  const gridItems: IItem[] = [
    {
      key: "test01",
      icon: React.createElement(DocumentTextLinkFilled),
      title: "Test 1",
      description: "Test document 01",
    },
    {
      key: "test02",
      icon: React.createElement(DocumentGlobeRegular),
      title: "Test 2",
      description: "This is just a test document 02",
    },
    {
      key: "test03",
      icon: React.createElement(DocumentTextToolboxRegular),
      title: "Test 3",
      description: "Test document 03",
    },
    {
      key: "test04",
      icon: React.createElement(DocumentPdfRegular),
      title: "Test 4",
      description: "Test document 04",
    },
    {
      key: "test05",
      icon: React.createElement(DocumentBulletListRegular),
      title: "Test with long title 5",
      description: "This is yet another test document 05",
    }
  ];

  return gridItems;
}

Again, for the sake of completeness, the icons are retrieved from the Fluent UI package with the following import:

import {
  DocumentBulletListRegular,
  DocumentPdfRegular,
  DocumentTextLinkFilled,
  DocumentGlobeRegular,
  DocumentTextToolboxRegular
} from '@fluentui/react-icons';

Conclusions

The PnP PropertyGridField control is a ready to use grid with awesome out of the box features. It might not be the best choice when it’s needed to display huge amount of data, this is because the maximum available width it’s restricted to the width of the property pane itself. Aside of the limitation on the width, I think this is can be an awesome addition when it comes to enable the users to select items offering a more complex layout rather than just some radio buttons.

There are plenty of other properties that I didn’t cover here. If you want to discover more about the PropertyGridField you can find the official documentation here.

Hope this helps!