How to use SPFx preconfiguredentries with examples

The SPFx preconfiguredentries property is a critical component of the Client Side Web Part manifest in the SharePoint Framework. So, what exactly is it, and what can we do with it?

• What is the spfx preconfigured entries property for?
• Adding spfx web parts is made easier with predefined entries
• Add spfx web part properties
• In the property pane, render the spfx web part properties
• Add labels for localization
• Set the default values for the spfx web part
• Enter a number of pre-configured spfx web part entries
• Enter an unconfigured instance of the web part

What is preconfiguredentries property for in spfx webpart

Client Side Web Parts in SharePoint Framework are made up of two parts: the manifest, which describes the Web Part, and the code, which extends the BaseClientSideWebPart class.

Here is how a sample Client Side Web Part manifest in the SharePoint Framework looks like:

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx/client-side-web-part-manifest.schema.json",
  "id": "8c4e3f98-2260-435f-8de6-32bbe3019253",
  "alias": "GalleryWebPart",
  "componentType": "WebPart",

  "version": "*",
  "manifestVersion": 2,

  "requiresCustomScript": false,
  "supportedHosts": ["SharePointWebPart", "TeamsPersonalApp", "TeamsTab", "SharePointFullPage"],
  "supportsThemeVariants": true,

  "preconfiguredEntries": [{
    "groupId": "5c03119e-3074-46fd-976b-c60198311f70", 
    "group": { "default": "Content" },
    "title": { "default": "Gallery" },
    "description": { "default": "Shows 5 most recent images" },
    "officeFabricIconFontName": "Picture",
    "properties": {
      "listName": "Images",
      "order": "reversed",
      "numberOfItems": 5,
      "style": "thumbnails"
    }
  }]
}

The manifest, as shown above, provides information such as the type of component, its id, and its version. But there’s also the preconfigured entries property to consider.

The preconfigured entries property contains information about the spfx Web Part that will be used in the Web Part Toolbox. The data from the preconfigured entries property is used to show the Web Part in the Toolbox and specify its default settings when it is added to the page whenever users wish to add the Web Part to the page.

Read Create SPFx Web Part with jQuery Accordion

Adding web parts is made easier with predefined entries

Here we will see how adding web parts using SharePoint Framework is made easier with predefined entries.

We will create a sample gallery web part with spfx to demonstrate how you may use predefined entries when creating web parts. Users may customize this web component to display items from a given list in a certain fashion by using numerous parameters.

For the sake of simplicity, we will skip the actual implementation of the web part functionality and instead concentrate on leveraging the preconfigured entries property to provide preconfigured versions of the gallery web part.

First, we will set up the spfx development environment, and then we will create new web parts by using the below command.

yo @microsoft/sharepoint

Once you create the web part follow the steps to see how adding web parts is made easier with pre-configured entries.

Add web part properties

Add spfx web part attributes to the web part manifest so that users may customize the gallery web component.

First, open the /src/webparts/gallery/GalleryWebPart.manifest.json file in the code editor.

Replace the following JSON in the properties section:

"preconfiguredEntries": [{
    "groupId": "5c03119e-3074-46fd-976b-c60198311f70", 
    "group": { "default": "Content" },
    "title": { "default": "Gallery" },
    "description": { "default": "Shows 5 most recent images" },
    "officeFabricIconFontName": "Picture",
    "properties": {
      "SpListName": "",
      "order": "",
      "numberOfItems": 5,
      "style": ""
    }
  }]

• listName: the name of the list from which the list items should be presented.
• order: indicates whether things should be shown in chronological or reverse chronological order.
• numberOfItems: indicates the number of items to display.
• style: determines how the items should be shown, for as thumbnails for displaying photos or a list for displaying documents.

The manifest-specified web part properties must also be added to the spfx web part properties interface.

Open the ./src/webparts/gallery/IGalleryWebPartProps.ts file in the code editor. Change its identifier to:

export interface IGalleryWebPartProps {
  spListName: string;
  order: string;
  numberOfItems: number;
  style: string;
}

When creating SharePoint Framework client-side web parts with React, you must edit the web part’s render() method, which utilizes that interface to construct an instance of the main React component, after altering the web part properties interface.

Open the ./src/webparts/gallery/GalleryWebPart.ts file in the code editor. Change the render() function of the web component to:

public render(): void {
    const element: React.ReactElement<IGalleryProps> = React.createElement(Gallery, {
      listName: this.properties.listName,
      order: this.properties.order,
      numberOfItems: this.properties.numberOfItems,
      style: this.properties.style
    });

    ReactDom.render(element, this.domElement);
  }

To display the values of the properties, update the main React component. Show the standard web part placeholder if the web component has not been specified. Open the ./src/webparts/gallery/components/Gallery.tsx file in the code editor and update the code to:

import * as React from 'react';
import styles from './Gallery.module.scss';
import { IGalleryProps } from './IGalleryProps';

export default class Gallery extends React.Component<IGalleryProps, any> {
  public render(): JSX.Element {
    if (this.needConfiguration()) {
      return <div className="ms-Grid" style={{ color: "#666", backgroundColor: "#f4f4f4", padding: "80px 0", alignItems: "center", boxAlign: "center" }}>
        <div className="ms-Grid-row" style={{ color: "#333" }}>
          <div className="ms-Grid-col ms-u-hiddenSm ms-u-md3"></div>
          <div className="ms-Grid-col ms-u-sm12 ms-u-md6" style={{ height: "100%", whiteSpace: "nowrap", textAlign: "center" }}>
            <i className="ms-fontSize-su ms-Icon ms-Icon--ThumbnailView" style={{ display: "inline-block", verticalAlign: "middle", whiteSpace: "normal" }}>
              </i><span className="ms-fontWeight-light ms-fontSize-xxl" style={{ paddingLeft: "20px", display: "inline-block", verticalAlign: "middle", whiteSpace: "normal" }}>Gallery</span>
          </div>
          <div className="ms-Grid-col ms-u-hiddenSm ms-u-md3"></div>
        </div>
        <div className="ms-Grid-row" style={{ width: "65%", verticalAlign: "middle", margin: "0 auto", textAlign: "center" }}>
          <span style={{ color: "#666", fontSize: "17px", display: "inline-block", margin: "24px 0", fontWeight: 100 }}>Show items from the selected list</span>
        </div>
        <div className="ms-Grid-row"></div>
      </div>;
    }
    else {
      return (
        <div className={styles.gallery}>
          <div className={styles.container}>
            <div className={`ms-Grid-row ms-bgColor-themeDark ms-fontColor-white ${styles.row}`}>
              <div className='ms-Grid-col ms-u-lg10 ms-u-xl8 ms-u-xlPush2 ms-u-lgPush1'>
                <span className="ms-font-xl ms-fontColor-white">
                  Welcome to SharePoint!
                </span>
                <p className='ms-font-l ms-fontColor-white'>
                  Customize SharePoint experiences using web parts.
                </p>
                <p className='ms-font-l ms-fontColor-white'>
                  List: {this.props.spListName}<br />
                  Order: {this.props.order}<br />
                  Number of items: {this.props.numberOfItems}<br />
                  Style: {this.props.style}
                </p>
                <a href="https://aka.ms/spfx" className={styles.button}>
                  <span className={styles.label}>Learn more</span>
                </a>
              </div>
            </div>
          </div>
        </div>
      );
    }
  }

  private needConfiguration(): boolean {
    return Gallery.isEmpty(this.props.spListName) ||
      Gallery.isEmpty(this.props.order) ||
      Gallery.isEmpty(this.props.style);
  }

  private static isEmpty(value: string): boolean {
    return value === undefined ||
      value === null ||
      value.length === 0;
  }
}

To display the values of the properties, update the main React component. Show the standard web part placeholder if the web component has not been specified. Open the./src/webparts/gallery/components/Gallery.tsx file in the code editor and update the code to:

import { IGalleryWebPartProps } from "../GalleryWebPart";

export interface IGalleryProps extends IGalleryWebPartProps {

 }

Read How to add custom controls in SPFx property pane

In the property pane, render the web part properties

The newly specified properties must be presented in the spfx web part property pane before a user may use them to customize the web part.

Open the./src/webparts/gallery/GalleryWebPart.ts file in the code editor. Change the @microsoft/sp-webpart-base import line in the top portion of the file to:

import {
  BaseClientSideWebPart
} from '@microsoft/sp-webpart-base';
import {
  IPropertyPaneConfiguration,
  PropertyPaneDropdown,
  PropertyPaneSlider,
  PropertyPaneChoiceGroup
} from '@microsoft/sp-property-pane';

In the same GalleryWebPart.ts file, update the code of propertypane setting:

protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
    return {
      pages: [
        {
          header: {
            description: strings.PropertyPaneDescription
          },
          groups: [
            {
              groupName: strings.BasicGroupName,
              groupFields: [
                PropertyPaneDropdown('spListName', {
                  label: strings.SpListNameFieldLabel,
                  options: [{
                    key: 'Documents',
                    text: 'Documents'
                  },
                  {
                    key: 'Images',
                    text: 'Images'
                  }]
                }),
                PropertyPaneChoiceGroup('order', {
                  label: strings.OrderFieldLabel,
                  options: [{
                    key: 'chronological',
                    text: strings.OrderFieldChronologicalOptionLabel
                  },
                  {
                    key: 'reversed',
                    text: strings.OrderFieldReversedOptionLabel
                  }]
                }),
                PropertyPaneSlider('numberOfItems', {
                  label: strings.NumberOfItemsFieldLabel,
                  min: 1,
                  max: 10,
                  step: 1
                }),
                PropertyPaneChoiceGroup('style', {
                  label: strings.StyleFieldLabel,
                  options: [{
                    key: 'thumbnails',
                    text: strings.StyleFieldThumbnailsOptionLabel
                  },
                  {
                    key: 'list',
                    text: strings.StyleFieldListOptionLabel
                  }]
                })
              ]
            }
          ]
        }
      ]
    };
  }

Add labels for localization in spfx web part properties

Now we will how to add labels for localizations to the code.

• Open the file./src/webparts/gallery/loc/mystrings.d.ts in the code editor. Change the code to:

declare interface IGalleryWebPartStrings {
  
  AppLocalEnvironmentSharePoint: string;
  AppLocalEnvironmentTeams: string;
  AppSharePointEnvironment: string;
  AppTeamsTabEnvironment: string;
  PropertyPaneDescription: string;
  BasicGroupName: string;
  SpListNameFieldLabel: string;
  OrderFieldLabel: string;
  OrderFieldChronologicalOptionLabel: string;
  OrderFieldReversedOptionLabel: string;
  NumberOfItemsFieldLabel: string;
  StyleFieldLabel: string;
  StyleFieldThumbnailsOptionLabel: string;
  StyleFieldListOptionLabel: string;
}

declare module 'GalleryWebPartStrings' {
  const strings: IGalleryWebPartStrings;
  export = strings;
}

• Open the./src/webparts/gallery/loc/en-us.js file and change the code to:

define([], function() {
  return {
    "PropertyPaneDescription": "Description",
    "BasicGroupName": "Group Name",
    "SpListNameFieldLabel": "List",
    "OrderFieldLabel": "Items order",
    "OrderFieldChronologicalOptionLabel": "chronological",
    "OrderFieldReversedOptionLabel": "reversed chronological",
    "NumberOfItemsFieldLabel": "Number of items to show",
    "StyleFieldLabel": "Items display style",
    "StyleFieldThumbnailsOptionLabel": "thumbnails",
    "StyleFieldListOptionLabel": "list",
    "AppLocalEnvironmentSharePoint": "The app is running on your local environment as SharePoint web part",
    "AppLocalEnvironmentTeams": "The app is running on your local environment as Microsoft Teams app",
    "AppSharePointEnvironment": "The app is running on SharePoint page",
    "AppTeamsTabEnvironment": "The app is running in Microsoft Teams"
  }
});

Now run the project by using the below command and you can see the below result by adding the gallery web part.

Because we did not set any default values for the web part, users must customize it each time they add it to the page. We may make this experience easier by supplying default options for the most typical cases.

Read @microsoft/generator-sharepoint update check failed

Set default values for spfx web part properties

Here we will set the default values of the properties for the spfx web part.

Assume that users often utilize the gallery web part to see the five most recently inserted images. Rather than forcing users to set up the web component individually each time, we could give them a preconfigured version that utilizes the relevant parameters.

Open the file./src/webparts/gallery/GalleryWebPart.manifest.json in the code editor. Change the current value in the preconfiguredEntries property to:

  "preconfiguredEntries": [{
    "groupId": "5c03119e-3074-46fd-976b-c60198311f70", 
    "group": { "default": "Content" },
    "title": { "default": "Gallery" },
    "description": { "default": "Shows 5 most recent images" },
    "officeFabricIconFontName": "Picture",
    "properties": {
      "SpListName": "Images",
      "order": "reversed",
      "numberOfItems": 5,
      "style": "thumbnails"
    }
  }]

Now to run the project, use the below command and you can see the default values are added to the properties

Enter a number of pre-configured spfx web part entries

Assume that another set of users often utilizes your gallery web part to display papers that have just been posted to their site. You may add another set of presets that meet their setup needs to assist them to utilize your web part.

Open the./src/webparts/gallery/GalleryWebPart.manifest.json file in the code editor. Change the property preconfiguredEntries to:

"preconfiguredEntries": [{
    "groupId": "5c03119e-3074-46fd-976b-c60198311f70", 
    "group": { "default": "Content" },
    "title": { "default": "Gallery" },
    "description": { "default": "Shows 5 most recent images" },
    "officeFabricIconFontName": "Picture",
    "properties": {
      "listName": "Images",
      "order": "reversed",
      "numberOfItems": 10,
      "style": "thumbnails"
    }
  },
  {
    "groupId": "5c03119e-3074-46fd-976b-c60198311f70",
    "group": { "default": "Content" },
    "title": { "default": "Recent documents" },
    "description": { "default": "Shows 10 most recent documents" },
    "officeFabricIconFontName": "Documentation",
    "properties": {
      "listName": "Documents",
      "order": "reversed",
      "numberOfItems": 15,
      "style": "list"
    }
  } ]

Now to run the project, use the below command and you can see the default values are added to the properties.

When you add the Recent documents web part to a page, it starts working right away thanks to its predefined settings.

Read SPFx Send Email using PnP

Enter an unconfigured instance of spfx web part

When developing web parts, there are frequently certain scenarios that the web component should handle. Having pre-configured entries for various instances makes it easier for people to use the online section.

Depending on how we construct our web part, it is feasible that it will handle other unknown circumstances. Users may not know they may use your web part for a different scenario if you simply give particular predefined entries. It may also be a good idea to provide a generic unconfigured form of your web element.

Open the./src/webparts/gallery/GalleryWebPart.manifest.json file in the code editor. Change the property preconfiguredEntries to:

"preconfiguredEntries": [{
    "groupId": "5c03119e-3074-46fd-976b-c60198311f70", 
    "group": { "default": "Content" },
    "title": { "default": "Gallery" },
    "description": { "default": "Shows 5 most recent images" },
    "officeFabricIconFontName": "Picture",
    "properties": {
      "listName": "Images",
      "order": "reversed",
      "numberOfItems": 10,
      "style": "thumbnails"
    }
  },
  {
    "groupId": "5c03119e-3074-46fd-976b-c60198311f70",
    "group": { "default": "Content" },
    "title": { "default": "Recent documents" },
    "description": { "default": "Shows 10 most recent documents" },
    "officeFabricIconFontName": "Documentation",
    "properties": {
      "listName": "Documents",
      "order": "reversed",
      "numberOfItems": 15,
      "style": "list"
    }
  },
  {
    "groupId": "5c03119e-3074-46fd-976b-c60198311f70",
    "group": { "default": "Content" },
    "title": { "default": "Gallery" },
    "description": { "default": "Shows items from the choosen list" },
    "officeFabricIconFontName": "CustomList",
    "properties": {
      "listName": "",
      "order": "",
      "numberOfItems": 15,
      "style": ""
    }
  }] 

To see the outcome, execute the following command to begin debugging the project:

gulp serve

When you access the web part toolbox to add the web part to the canvas, we will notice that there are now three web parts available for users to select.

Download SPFx Solution

To use the spfx solution, you can download the solution file, unzip the file and run the solution with the below command.

npm i

Conclusion

In this tutorial, we saw how to use SharePoint Framework preconfiguredentries. So here are the topics we cover:

• What is the spfx preconfigured entries property for?
• Adding spfx web parts is made easier with predefined entries
• Add spfx web part properties
• In the property pane, render the spfx web part properties
• Add labels for localization
• Set the default values for the spfx web part
• Enter a number of pre-configured spfx web part entries
• Enter an unconfigured instance of the web part

You may like the following spfx tutorials:

• Display SharePoint list items using SPFx
• SPFx Fluent UI Basic List Example
• SPFx fluent UI react dropdown example
• SPFx SwatchColorPicker Office UI Fabric React Control example
• SharePoint Framework – Fluent UI React ChoiceGroup (Radio Button) and Checkbox Example
• How to Configure Web Part Icon in SPFx