Configure SharePoint Framework Properties and PreconfiguredEntries

When building SharePoint Framework (SPFx) web parts, we often add configurable settings (called web part properties) so users can customize how the web part works.

For example, instead of showing items from one fixed SharePoint list, you can let users choose which list to display, control sorting, or set the number of items to be shown in the web part.

To make this even easier, SPFx provides a feature called preconfiguredEntries, which lets you define default values for your web part before users add it to a page. This is especially useful when you want to offer multiple versions of the same webpart with different default settings for various scenarios.

In this article, I’ll explain how to configure SPFx web part properties and use preconfiguredEntries with practical examples.

SPFx Webpart preconfiguredEntries Property

The preconfiguredEntries property provides information about your SPFx web part. When users add a web part to a SharePoint site page, the information from the preconfiguredEntries property is used to display.

Additionally, it enables users to quickly add web parts with default settings, eliminating the need for manual configuration each time. This property is present in the manifest.json file, located in src/webparts/projectListViewer/projectListViewerWebpart.manifest.json.

Let’s quickly understand what properties this preconfiguredEntries array contains.

Property	Data Type	Purpose
groupId	string	Used to group similar web parts together in the toolbox.
group	ILocalizedString	The group name in the web part picker to contain the web part in the classic page. If no value is provided, the web part is displayed in the Miscellaneous group.
title	ILocalizedString	The name shown for the web part when adding it to a page.
description	ILocalizedString	The web part description is displayed in the toolbox tooltips.
officeFabricIconFontName	string	The icon shown for the web part.
properties	TProperties	These are the default settings that will be applied when the web part is added.

I built a sample SPFx web part with several properties to show how you can use preconfiguredEntries in SPFx. In the example below, you can see that the web part has default values for its properties on the right side pane.

Follow the sections below to achieve this!

How to Add SPFx Webpart Properties

I hope by this time you know how to set up the SPFx development environment. If not, follow this article: How to Set up SharePoint Framework development environment.

In this section, we will start by creating an SPFx web part and add some properties to it. Follow the steps below!

1. Open the Command Prompt and run the following commands to create a directory and navigate into it.

md react-preconfiguredentries
cd react-preconfiguredentries

2. Then, in the same directory, run the following command:

yo @microsoft/sharepoint

This will ask you the following questions. Answer them as mentioned below!

• What is your solution name? react-preconfiguredentries
• Which type of client-side component to create? WebPart
• Add a new Web part to the solution react-preconfiguredentries.
• What is your Web part name? ProjectListViewer
• Which template would you like to use? React

Then it will take some time to create the solution. 

3. Once it is created successfully! Run the code . to enter into the project.
4. Now, we’ll add properties to this web part, so open the manifest.json file present in src/webparts/projectListViewer/projectListViewerWebpart.manifest.json. Then update the properties object in the preconfiguredEntries array.

  "preconfiguredEntries": [{
    //......
    "properties": {     
      "webPartTitle": "",
      "projectList":"",
      "description": "",
      "maxItems":10,
      "groupByField":"",
      "showCompleted":false,
      "order": ""
    }
  }]

Here:

• webPartTitle = To display the web part name dynamically.
• projectList = Choose which SharePoint list to pull project data from.
• description = Description of the project.
• maxItems = Limit the number of projects displayed at once.
• groupByField = E.g., Department, Owner, or Status
• showCompleted = Option to include or hide completed projects.
• order = To display items either in chronological or reverse order.

6. Next, let’s define the data types for these properties in the Props.ts file like this:

export interface IProjectListViewerProps {
  description: string;
  isDarkTheme: boolean;
  environmentMessage: string;
  hasTeamsContext: boolean;
  userDisplayName: string;
  webPartTitle:string;
  projectList: string;
  maxItems: number;
  groupByField: string;
  showCompleted: boolean;
  order: string;
}

5. Open the .ts file, which is located in \src\webparts\projectListViewer\ProjectListViewerWebPart.ts, and update the interface with the code below.

export interface IProjectListViewerWebPartProps {
  webPartTitle: string;
  projectList: string;
  description: string;
  maxItems: number;
  groupByField: string;
  showCompleted: boolean;
  order:string;
}

7. In the same .ts file, update the render() method with the below code.

  public render(): void {
    const element: React.ReactElement<IProjectListViewerProps> = React.createElement(
      ProjectListViewer,
      {
        description: this.properties.description,
        isDarkTheme: this._isDarkTheme,
        environmentMessage: this._environmentMessage,
        hasTeamsContext: !!this.context.sdks.microsoftTeams,
        userDisplayName: this.context.pageContext.user.displayName,
        webPartTitle: this.properties.webPartTitle,
        projectList: this.properties.projectList,
        maxItems:this.properties.maxItems,
        groupByField: this.properties.groupByField,
        showCompleted: this.properties.showCompleted,
        order: this.properties.order
      }
    );

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

This render method creates and renders the React component with all the web part properties passed as props, so it can display accordingly.

8. Now, open the mystring.d.ts file located inside the src/loc folder and update it with the code below to define all the text labels (like field names, messages, and dropdown options) that our web part will use.

declare interface IProjectListViewerWebPartStrings {
  PropertyPaneDescription: string;
  BasicGroupName: string;
  WebPartTitleFieldLabel:string;
  ProjectListFieldLabel: string;
  DescriptionFieldLabel: string;
  MaxItemsFieldLabel: string;
  GroupByFieldLabel: string;
  GroupByFieldDepartmentOptionLabel: string;
  GroupByFieldOwnerOptionLabel: string;
  GroupByFieldStatusOptionLabel: string;
  ShowCompletedFieldOnText: string;
  ShowCompletedFieldOffText: string;
  ShowCompletedFieldLabel: string;
  OrderFieldLabel: string;
  OrderFieldChronologicalOptionLabel: string;
  OrderFieldReversedOptionLabel: string;
  AppLocalEnvironmentSharePoint: string;
  AppLocalEnvironmentTeams: string;
  AppLocalEnvironmentOffice: string;
  AppLocalEnvironmentOutlook: string;
  AppSharePointEnvironment: string;
  AppTeamsTabEnvironment: string;
  AppOfficeEnvironment: string;
  AppOutlookEnvironment: string;
  UnknownEnvironment: string;
}

declare module 'ProjectListViewerWebPartStrings' {
  const strings: IProjectListViewerWebPartStrings;
  export = strings;
}

It helps organize all our display text in one place, making it easier to translate the web part into other languages later.

9. Then, open the en-us file inside the src/loc folder and update it with the code below. This file contains the actual text that our web part displays to users, including field labels, dropdown options, and messages.

define([], function() {
  return {
    "PropertyPaneDescription": "Description",
    "BasicGroupName": "Group Name",
    "WebPartTitleFieldLabel": "Webpart Title",
    "ProjectListFieldLabel": "Project List",
    "DescriptionFieldLabel": "Description Field",
    "MaxItemsFieldLabel": "Max Items to Display",
    "GroupByFieldLabel": "Group By Field",
    "ShowCompletedFieldLabel": "Show Completed",
    "OrderFieldLabel": "Order",
    "OrderFieldChronologicalOptionLabel": "Chronological",
    "OrderFieldReversedOptionLabel": "Reversed",
    "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",
    "AppLocalEnvironmentOffice": "The app is running on your local environment in office.com",
    "AppLocalEnvironmentOutlook": "The app is running on your local environment in Outlook",
    "AppSharePointEnvironment": "The app is running on SharePoint page",
    "AppTeamsTabEnvironment": "The app is running in Microsoft Teams",
    "AppOfficeEnvironment": "The app is running in office.com",
    "AppOutlookEnvironment": "The app is running in Outlook",
    "UnknownEnvironment": "The app is running in an unknown environment"
  }
});

These labels match the keys we defined earlier in the mystrings.d.ts file, making our web part easier to update.

10. In the \src\webparts\projectListViewer\ProjectListViewerWebPart.ts, update the ‘@microsoft/sp-property-pane’ import statement with the below code.

import {
  type IPropertyPaneConfiguration,
  PropertyPaneTextField,
  PropertyPaneDropdown,
  PropertyPaneToggle,
  PropertyPaneSlider,
  PropertyPaneChoiceGroup
} from '@microsoft/sp-property-pane';

Here, we are importing the text field, dropdown, toggle, slider, and choice group controls for the property pane.

11. Now, update the getPropertyPaneConfiguration() method with the code below in the .ts file.

   protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
    return {
      pages: [
        {
          header: {
            description: strings.PropertyPaneDescription
          },
          groups: [
            {
              groupName: strings.BasicGroupName,
              groupFields: [
                PropertyPaneTextField('webPartTitle', {
                label: strings.WebPartTitleFieldLabel,
                }),
                PropertyPaneDropdown('projectList', {
                 label: strings.ProjectListFieldLabel,
                 options: [
                  { key: 'ProjectList1', text: 'Project List 1' },
                  { key: 'ProjectList2', text: 'Project List 2' },
                  { key: 'ProjectList3', text: 'Project List 3' }
                ]
               }),
              PropertyPaneTextField('description', {
                  label: strings.DescriptionFieldLabel
                }),
              PropertyPaneSlider('maxItems', {
                label: strings.MaxItemsFieldLabel,
                min: 1,
                max: 25
              }),
              PropertyPaneDropdown('groupByField', {
                label: strings.GroupByFieldLabel,
                options: [
                  { key: 'Department', text: strings.GroupByFieldDepartmentOptionLabel },
                  { key: 'Owner', text: strings.GroupByFieldOwnerOptionLabel },
                  { key: 'Status', text: strings.GroupByFieldStatusOptionLabel }
                ]
              }),
            PropertyPaneToggle('showCompleted', {
                label: strings.ShowCompletedFieldLabel,
                onText: strings.ShowCompletedFieldOnText,
                offText: strings.ShowCompletedFieldOffText
              }),
            PropertyPaneChoiceGroup('order', {
                label: strings.OrderFieldLabel,
                options: [
                  { key: 'Chronological', text: strings.OrderFieldChronologicalOptionLabel},
                  { key: 'Reversed', text: strings.OrderFieldReversedOptionLabel }                
                ]
              })
              ]
            }
          ]
        }
      ]
    };
  }

In the above code, we added seven properties to our SPFx web part, each with various types of controls, including a toggle, a dropdown, and a choice group.

Also, if you observe each property label and dropdown, the choice group ‘text’, which takes values from the mystring.d.ts file, which we defined in previous steps, e.g., strings.WebPartTitleFieldLabel

12. Now, we’ll start debugging this web part by running the following command.

gulp serve

Now, in the local workbench, you’ll see the sample web part displayed. When you click the edit icon on the left side of the web part, the property pane will open on the right. Here, you can see all the properties we added earlier.

Here, we are not focusing on the web part functionality; instead, we are focusing on how to add and set web part properties, as well as the usage of preconfiguredEntries.

Till now, we have seen how to create a SPFx web part and add properties to it. So, in the section below, we’ll see how to display the input that we provided in the web part property panes.

Render the User Input from the Property Pane

Open the \src\webparts\projectListViewer\components\ProjectListViewer.tsx file, and update the render() method within the export default class with the code below.

  public render(): React.ReactElement<IProjectListViewerProps> {
    const {
      description,
      hasTeamsContext,
      webPartTitle,
      projectList,
      maxItems,
      groupByField,
      showCompleted,
      order
    } = this.props;

    return (
      <section className={`${styles.projectListViewer} ${hasTeamsContext ? styles.teams : ''}`}>
         <div className= {styles.mainContainer}>
          <h2 className={styles.welcome}> {escape(webPartTitle)}</h2>
          <h3 className={styles.welcomeh2}>Web part property values:</h3>
          <div> 
             <ul className={styles.propertyList}>
              <li>Description: <strong>{escape(description)}</strong></li>
              <li>Project Title: <strong>{escape(projectList)}</strong></li>
              <li>Max Items to Display: <strong>{maxItems}</strong></li>
              <li>Group By Field: <strong>{groupByField}</strong></li>
              <li>Show Completed: <strong>{showCompleted ? 'Yes' : 'No'}</strong></li>
              <li>Order: <strong>{order}</strong></li>      
             </ul>
          </div>
        </div>
      </section>
    );
  }

Here,

• const {…..} = this.props; It extracts the property values from this.props so they can be used directly in the render method without repeating this.props every time.
• Within the return(), we are just calling the properties by their names.
• {escape()} = This method is used to display the string property values in the web part.

To apply styles for this web part, update the .scss file with the code below.

.welcome {
  text-align: center;
  font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
  font-size: 1.7em;
  color: #006A71;
  padding-top: 5px;
  padding-bottom: 5px;
}
.welcomeh2{
  text-align: left;
  font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
  font-size: 1.3em;
  color: #006971ac;
  padding-left: 38px;
}
.mainContainer{
  background-color:rgba(128, 128, 128, 0.075);
  border-style: solid;
  border-width: 5px;
  border-color:rgba(90, 93, 90, 0.975);
  width: 700;
}
.welcomeImage {
  width: 100%;
  max-width: 420px;
}
.propertyList{
  text-align: left;
  list-style: none;
  font-style: normal;
  font-size: medium;
  color: rgb(10, 10, 11);
}

Now, save the changes, then rerun the gulp serve command to see the changes. This time, whatever we entered in the web part property pane control is displayed immediately within the web part.

But if you observe carefully, by default, all the web part properties are empty, so no property value is displayed in the web part. Here, the preconfiguredEntries are used to set default values for the web part properties.

How to Use SPFx preconfiguredEntries Property

Open the src\webparts\projectListViewer\ProjectListViewerWebPart.manifest.json file. Update the preconfiguredEntries array with the code below.

  "preconfiguredEntries": [{
    "groupId": "5c03119e-3074-46fd-976b-c60198311f70", // Advanced
    "group": { "default": "Advanced" },
    "title": { "default": "ProjectListViewer" },
    "description": { "default": "ProjectListViewer description" },
    "officeFabricIconFontName": "Page",
    "properties": {     
      "webPartTitle": "Project Tracking Web Part",
      "projectList":"Project List 1",
      "description":"Project Description",
      "maxItems":10,
      "groupByField":"Department",
      "showCompleted":false,
      "order": "Reversed"
    }
  }]

So in this code, we set the default values for the web part properties. Run the gulp serve command to test it once. This time, you can see the web part is rendered with the default values.

This way, we can set the default values for the SPFx web part. Along with this, we can also do some other things with the preconfiguredEntries property, such as specifying multiple preconfigured web part entries.

To understand this, imagine you have one web part that you want to display with different default settings in various situations.

For example, let’s say we want to offer two versions of this current project web part.

1. Team View
   • webPartTitle = Team Projects
   • projectList = ProjectList1
   • groupByField = Owner
   • maxItems = 10
   • showCompleted =Yes
   • order = Chronological

2. Department View
   • webPartTitle = Department Overview
   • projectList = ProjectList2
   • groupByField = Department
   • maxItems = 15
   • showCompleted = No
   • order = Reverse

Now, when users go to add the web part in SharePoint, they’ll see two options for our project web part: “Team View” and “Department View,” each with different pre-filled settings. preconfiguredEntries help you define those ready-to-use versions; this saves users time. Let’s see how to achieve this in the section below.

Specify Multiple preconfigured Webpart Entries

Look at the example below, in the local workbench for this current project web part, I have two different setups. So when I added those setups, the default entered web part properties are there. For one web part, we have multiple setups.

To achieve this, update the preconfiguredEntries in the manifest.json file with the code below.

  "preconfiguredEntries": [{
    "groupId": "5c03119e-3074-46fd-976b-c60198311f70", // Advanced
    "group": { "default": "Advanced" },
    "title": { "default": "Team Projects" },
    "description": { "default": "Displays projects grouped by Owner from Project List 1" },
    "officeFabricIconFontName": "Family",
    "properties": {     
      "webPartTitle": "Team Projects",
      "projectList":"ProjectList1",
      "description":"Team focused view",
      "maxItems":10,
      "groupByField":"Owner",
      "showCompleted":true,
      "order": "Chronological"
    }
  },
  {
    "groupId": "5c03119e-3074-46fd-976b-c60198311f70", 
    "group": { "default": "Advanced" },
    "title": { "default": "Department Overview" },
      "description": {"default": "Displays projects grouped by Department from Project List 2"},
      "officeFabricIconFontName": "ProjectLogo32",
      "properties": {
        "description": "Department focused view",
        "webPartTitle": "Department Overview",
        "projectList": "ProjectList2",
        "maxItems": 15,
        "groupByField": "Department",
        "showCompleted": false,
        "order": "Reversed"
      }
    }
]

Then, run the’ gulp serve’ command. It will open the local workbench URL. Click on the + icon. Under Local, you can see two different versions of our SPFX project web part.

If you also want your default configuration, along with the two setups, simply update the preconfiguredEntries with the code below. This time, you’ll be able to see three setups; the third one will not contain any default values for the web part properties. The user can then choose on their own because those are empty.

  "preconfiguredEntries": [{
    "groupId": "5c03119e-3074-46fd-976b-c60198311f70", // Advanced
    "group": { "default": "Advanced" },
    "title": { "default": "Team Projects" },
    "description": { "default": "Displays projects grouped by Owner from Project List 1" },
    "officeFabricIconFontName": "Family",
    "properties": {     
      "webPartTitle": "Team Projects",
      "projectList":"ProjectList1",
      "description":"Team focused view",
      "maxItems":10,
      "groupByField":"Owner",
      "showCompleted":true,
      "order": "Chronological"
    }
  },
  {
    "groupId": "5c03119e-3074-46fd-976b-c60198311f70", 
    "group": { "default": "Advanced" },
    "title": { "default": "Department Overview" },
      "description": {"default": "Displays projects grouped by Department from Project List 2"},
      "officeFabricIconFontName": "ProjectLogo32",
      "properties": {
        "description": "Department focused view",
        "webPartTitle": "Department Overview",
        "projectList": "ProjectList2",
        "maxItems": 15,
        "groupByField": "Department",
        "showCompleted": false,
        "order": "Reversed"
      }
    },
      {
    "groupId": "5c03119e-3074-46fd-976b-c60198311f70", 
    "group": { "default": "Advanced" },
    "title": { "default": "Project List Viewer WebPart" },
      "description": {"default": "ProjectListViewer"},
      "officeFabricIconFontName": "Page",
      "properties": {
        "description": "",
        "webPartTitle": "",
        "projectList": "",
        "maxItems": 10,
        "groupByField": "",
        "showCompleted": false,
        "order": ""
      }
    }
]

This way, we can use the SPFx web part’s preconfiguredEntries property.

To deploy the solution, create the package by running the commands below and uploading it to the app catalog site.

gulp bundle --ship

gulp package-solution --ship

Once you run the above commands, it will create the .sppkg file in the sharepoint\solution folder.

I hope you found this article helpful! In this article, I explained how to add and set up properties in an SPFx web part and how to display those property values inside the web part.

I also explained how to use preconfiguredEntries to set default values in an SPFx web part. Then I explained how to create multiple versions of the same web part using different preconfigured entries. You can follow this guide to create different versions of a web part with varying default settings.

You may like the following SPFx tutorials:

• How to add custom controls in SPFx property pane
• SPFx Property Pane Controls
• How to Add Multiple WebParts To Single SPFx Solution?
• Configure SharePoint Framework Web Part Icon
• SharePoint Framework – Fluent UI React ChoiceGroup (Radio Button) and Checkbox Example