Explore the PropertyFieldSearch control from the PnP property controls

Introduction

Proceeding our dive into the PnP reusable property pane controls I want to cover the PropertyFieldSearch 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. The sample solution contains a simple web part that shows how the PropertyFieldSearch works.

Visual appearance

Before switching to the code section I want to cover the resulting user interface. Since the PropertyFieldSearch control is used in the web part property pane I will cover only the property pane interface.

In the sample solution I’ve prepared there are four different instances:

Each control is inserted in a specific property pane group, the control itself doesn’t have a label.

Starting with the minimal instance the resulting UI is a text box with a search icon and with no place holder:

When inserting a text the control will change a little bit:

The icon will be hidden until the text box has the focus, once the control doesn’t have the focus it will become as following:

The icon on the right is used to clear the inserted text.

It’s possible to define a custom text for the place holder:

The control also supports a different rendering if needed. Instead of the text box layout is possible to have a minimal interface:

At last, the instance with events shows the possible events that the control offers. The layout is the same of the other instances but, in the sample, I’ve used the events to write in the browser’s console.

I will cover the events better in the code section.

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

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

import { PropertyFieldSearch } from "@pnp/spfx-property-controls/lib/PropertyFieldSearch";

To enable the control to set the properties of the web part I defined the following interface:

export interface IPropertyFieldSearchWebPartProps {
  searchValueMinimal: string;
  searchValuePreFilled: string;
  searchValueUnderlined: string;
  searchValueWithEvents: string;
}

Inside the web part getPropertyPaneConfiguration function I defined the various control instances, let’s cover those!

Minimal instance

In the minimal instance there are specified only the required properties. Those properties are the key and value ones. The key property define an identifier for the control instance. The value property sets the value shown in the control.

PropertyFieldSearch("searchValueMinimal", {
  key: "searchMinimal",
  value: this.properties.searchValueMinimal, })

Custom placeholder

The control offers the ability to specify a custom placeholder instead of an empty text box. To define the placeholder it’s enough to set a value to the placeholder property:

PropertyFieldSearch("searchValuePlaceholder", {
  key: "searchPlaceholder",
  placeholder: strings.PlaceHolder,
  value: this.properties.searchValuePlaceholder,
})

Underlined instance

As shown in the visual appearance section the underlined property let’s you set a slightly different user interface. The property, by default, is set to false. To enable the different appearance it’s enough to set the property to true.

PropertyFieldSearch("searchValueUnderlined", {
  key: "searchUnderlined",
  placeholder: strings.PlaceHolder,
  value: this.properties.searchValueUnderlined,
  underlined: true,
})

Instance with events

In my opinion the most interesting properties of the control are the events ones. Let’s have a look at the instance definition and then let’s cover each of the available events:

PropertyFieldSearch("searchValueWithEvents", {
  key: "search",
  placeholder: strings.PlaceHolder,
  value: this.properties.searchValueWithEvents,
  onSearch: this._onSearch,
  onEscape: this._onEscape,
  onClear: this._onClear, })

The onSearch event offers the ability to intercept when a user press the enter key after the insertion of the text. The method that I’ve defined simply trace the call in the browser’s console.

private _onSearch = (value: string) => {
  console.log("onSearch called!", value);
}

The “X” icon on the right side of the control is used to clear all the inserted text. When clicking on the clear icon the onClear event is called. As the previous method also this will only trace the call in the sample.

private _onClear = (ev: any) => {
  console.log("onClear called!", ev);
}

The last event is the onEscape one. This event will be called when the user hit the escape key. To be noted that when pressing the key, other than the onEscape event also the onClear event will be called.

private _onEscape = (ev: any) => {
  console.log("onEscape called!", ev);
}

Conclusions

The PropertyFieldSearch control is a ready to go and styled text input. It offers various event handling and also a very nice UI interface and all of this comes with just a few lines of code.

If you want to know a little bit more about the control you can have a look at the official documentation.

Hope this helps!