One of the most useful features of SPFx is the property pane , which allows end-users to configure web parts with several properties.
The property pane has three key metadata: a page, an optional header, and at least one group.
Pages provide you the flexibility to separate complex interactions and put them into one or more pages. Pages contain a header and groups.
Headers allow you to define the title of the property pane page.
Groups allow you to define the various sections or fields for the property pane through which you want to group your field sets.
In this blog post, we will explore how to use the property pane, as usual first let’s see the result and then the code.
This is the resulting not configured web part:
This is the the resulting situation with the web part and the property pane both open:
The property pane in detail not configured and configured:
Configuring the entries in the property pane updates the properties in the web part:
Now that we have an idea of the resulting UI let’s see the code in detail.
The code
After creating a web part solution using the Yeoman generator @microsoft/sharepoint you’ll have a web part with a default property description
that can be configured in the property pane.
Following the already existing code we have to define the web part properties that we want to be configured in the property pane, in this sample named PropertyPaneSample
(yep, no imagination) we have five different properties to show a few of the controls that can be used in the property pane, to do so in the IPropertyPaneSampleWebPartProps
I defined the following:
export interface IPropertyPaneSampleWebPartProps {
description: string;
checkboxValue: boolean;
dropdownValue: string;
toggleValue: boolean;
sliderValue: number;
}
To define the content of the property pane you have to use the method getPropertyPaneConfiguration
inside of the {Your web part name}WebPart.ts
file, in the sample the name is PropertyPaneSampleWebPart.ts
. The getPropertyPaneConfiguration
returns an object composed, as written in the post introduction, by an array of pages
and each page is composed of a property header
which contains the description of the page and a property groups
which is an array of objects composed mainly of the groupName
and groupFields
properties.
protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
return {
pages: [
{
header: {
description: strings.PropertyPaneDescription,
},
groups: [
{
groupName: strings.BasicGroupName,
groupFields: [
// omitted for brevity
],
},
],
},
],
};
}
The groupName
is fairly clear that is a string containing the group name.
The groupFields
contains all the fields that we want to configure in the group.
In the sample the groupFields
properties contains the various controls that we use to configure the web part, the content of the property is the following:
PropertyPaneTextField("description", {
label: strings.DescriptionFieldLabel,
}),
PropertyPaneCheckbox("checkboxValue", {
text: strings.CheckboxValueFieldLabel,
checked: this.properties.checkboxValue,
}),
PropertyPaneDropdown("dropdownValue", {
label: strings.DropdownValueFieldLabel,
options: [
{ key: "1", text: "One" },
{ key: "2", text: "Two" },
{ key: "3", text: "Three" },
{ key: "4", text: "Four" },
{ key: "5", text: "Five" },
],
}),
PropertyPaneToggle("toggleValue", {
label: strings.ToggleValueFieldLabel,
onText: "On",
offText: "Off",
checked: this.properties.toggleValue,
}),
PropertyPaneSlider("sliderValue", {
label: strings.SliderValueFieldLabel,
min: 0,
max: 100,
step: 1,
showValue: true,
value: 50,
}),
As you can see we have some helper methods that create a specific control in our property pane, the names are esplicative but to be clear here is a clarification:
-
PropertyPaneTextField
: displays a text box. -
PropertyPaneCheckbox
: displays a checkbox. -
PropertyPaneDropdown
: displays a dropdown control where you have to define which are the possible selectable options. -
PropertyPaneToggle
: displays a toggle where you can also define the labels for the on or off state. -
PropertyPaneSlider
: displays a slider, you can specify properties such as themin
andmax
supported values and also thestep
of the slider.
Once that you have set up your property pane you can now pass the configuration properties into the implementation of your web part control. In the sample solution I passed all the properties to the control class inside the render method of the PropertyPaneSampleWebPart
class:
public render(): void {
const element: React.ReactElement<IPropertyPaneSampleProps> =
React.createElement(PropertyPaneSample, {
description: this.properties.description,
checkboxValue: this.properties.checkboxValue,
dropdownValue: this.properties.dropdownValue,
toggleValue: this.properties.toggleValue,
sliderValue: this.properties.sliderValue,
});
ReactDom.render(element, this.domElement);
}
Inside the PropertyPaneSample
control I simply display the values to have a visual representation of the changes.
So this is how to use the property pane to configure your web part!
If you want to discover more regarding the default property pane controls of SPFx you can check the official documentation here, it’s also worth mentioning that PnP have it’s own custom controls for the property pane, if you’re interested follow this link to check the official documentation, I recommend to have a look at all the available controls to avoid writing a custom one that maybe already exists.
If you want to check the sample solution I made for this post you can check it here.
Hope that helps!
Top comments (0)