Create and Deploy SharePoint Framework (SPFx) extension field customizer

In this SharePoint Framework tutorial, we will discuss what is a field customizer extension in SPFx.

And we will also discuss how to create a SharePoint framework extension field customizer and deploy it to SharePoint Online.

And how to apply SPFx field customizer extension to existing SharePoint list columns using PnP PowerShell command.

I have also recorded a video on how to create and deploy SPFx field customizer in SharePoint Online Office 365.

SharePoint framework extension field customizer

By using SPFx field customizers, we can modify list views, we can extend views in SharePoint Online site.

You can check my previous article on SharePoint Framework (SPFx) Extensions Application Customizer Example and SPFx fluent UI react dropdown example.

Check out the complete video on the SPFx field customizer.

Create SPFx Field Customizer Extension

Now, we will see how to create a field customizer extension in SPFx.

Before starting, make sure, you have set up your SharePoint framework development environment.

I also prefer to use Visual studio code as the code editor for SPFx.

Few steps are the same as we develop an SPFx client side web part or application customizer.

Open Node.js command prompt and run the below command to create directory.

md FieldCustomizerDemo
cd FieldCustomizerDemo

Then run the Yeoman SharePoint Generator.

yo @microsoft/sharepoint

Then you can select the options like below:

• What is your solution name?
• Then select SharePoint Online only (latest) for the baseline packages.
• Where you want to place the files? Select Use the current folder
• Then Select N, to allow the solution to be deployed to all sites immediately.
• Select N, select solution contains unique permissions.
• Then select Extension, which type of client-side component to create?
• Then which type of client-side extension to create? Select Field Customizer from (Application Customizer/Field Customizer/ListViw Command Sets)

Then you can provider the Field customizer name and description like below:

Then it will take sometime and create the solution for us.

Run the below command to open the solution using visual studio code.

code .

You can check the solution looks like below:

Here, the .ts file is the important file which we can modify to write our code.

If you will open the .ts file, you can see by default it will import the BaseFieldCustomizer like below:

import {
  BaseFieldCustomizer,
  IFieldCustomizerCellEventParameters
} from '@microsoft/sp-listview-extensibility';

In a SPFx field customizer, the below 3 methods are very important.

• onInit(): The onInit() method get called after this.context and this.properties are assigned, but before the page DOM is ready. onInit() returns a promise that you can use to perform asynchronous operations; onRenderCell() is not called until your promise has resolved. If you don’t need that, simply return Promise.resolve();

By default the code looks like below:

@override
  public onInit(): Promise<void> {
    // Add your custom initialization to this method.  The framework will wait
    // for the returned promise to resolve before firing any BaseFieldCustomizer events.
    Log.info(LOG_SOURCE, 'Activated FieldCustomizerDemoFieldCustomizer with properties:');
    Log.info(LOG_SOURCE, JSON.stringify(this.properties, undefined, 2));
    Log.info(LOG_SOURCE, `The following string should be equal: "FieldCustomizerDemoFieldCustomizer" and "${strings.Title}"`);
    return Promise.resolve();
  }

• onRenderCell(): onRenderCell() event triggered when each cell is rendered. Here we can use the event.domElement HTML element to extend our functionality.

We can use the event.fieldValue to get the column or cell value. The default code look like below:

@override
  public onRenderCell(event: IFieldCustomizerCellEventParameters): void {
    // Use this method to perform your custom cell rendering.
    const text: string = `${this.properties.sampleText}: ${event.fieldValue}`;

    event.domElement.innerText = text;

    event.domElement.classList.add(styles.cell);
  }

• onDisposeCell(): onDisposeCell() is used to free up resources that were allocated while rendering.

The default code looks like below:

@override
  public onDisposeCell(event: IFieldCustomizerCellEventParameters): void {
    // This method should be used to free any resources that were allocated during rendering.
    // For example, if your onRenderCell() called ReactDOM.render(), then you should
    // call ReactDOM.unmountComponentAtNode() here.
    super.onDisposeCell(event);
  }

Here we have a SharePoint Online list as Project Status list which has a PercentageCompleted column and the list looks like below:

Now, we will enhance the SharePoint list view with some CSS.

We will write the code in the onRenderCell method. Modify the code like below:

@override
  public onRenderCell(event: IFieldCustomizerCellEventParameters): void {
    if (this.context.field.internalName === 'PercentageCompleted') {

      let value: number = parseInt(event.fieldValue);
      if(value<50)      
      {
        event.domElement.innerHTML =`<div class='${styles.red}'>
        ${event.fieldValue}</div>
        `;
      }
      else if(value>50 && value<90) 
      {
        event.domElement.innerHTML =`<div class='${styles.yellow}'>
        ${event.fieldValue}</div>
        `;
      }
      else
      {
        event.domElement.innerHTML =`<div class='${styles.green}'>
        ${event.fieldValue}</div>
        `;
      }       
    }
  }

Here, I have used the event.fieldValue which will provide the column value.

Here, I have added the .green, .red, and .yellow css class in the .scss file.

The SpFxFieldCustWpFieldCustomizer.module.scss file looks like below:

.FieldCustomizerDemo {
  .cell {
    background-color: "[theme:themePrimary, default:#e5e5e5]";
    display: 'inline-block';
  }
}
.green {
  background-color:green;
  width: 100px;
  height: 25px;
  color: white;
}

.red {
  background-color:red;
  width: 100px;
  height: 25px;
  color: white;
}

.yellow {
  background-color:yellow;
  width: 100px;
  height: 25px;
}

Now, Open the Config/serve.json file.

Here we need to replace the below two things:

• pageURL: Here we need to provide the SharePoint Online list URL
• InternalFieldName: Here we need to provide the column internal name. I am using here the PercentageCompleted column.

The serve.json file looks like below:

Now you can run the below command.

gulp serve

Now in the dialog box, it will ask to allow debug scripts, click on Load debug scripts like below:

Finally, you can see the list view looks like below:

Deploy SharePoint Framework Field Customizer Extension

Now we will see how to deploy the SPFx field customizer to SharePoint Online Office 365.

If you have not created an app catalog site, then you can create an app catalog site in SharePoint Online.

Also if you want the column to be created as a site column, then you can modify in the SharePoint\assets\elements.xml file.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
    <Field ID="{45b44c3a-cf64-4503-8a0b-4916703abe71}"
            Name="PercentageCompleted"
            DisplayName="PercentageCompleted"
            Type="Number"
            Min="0"
            Required="FALSE"
            Group="SPFx Columns"
            ClientSideComponentId="eb51471d-393d-4a5c-b689-158aaca5f84b">
    </Field>
</Elements>

Now, run the below command to bundle and packages the solution (One by One in the same order).

gulp build
gulp bundle --ship
gulp package-solution --ship

Then it will generate the .sppkg file which we need to upload into the App Catalog site.

Open the folder, drag and drop the .sppkg file into the App catalog site (Apps for SharePoint).

Click on Deploy.

You can see the it is deployed successfully.

Now you can open the SharePoint Online site, from gear icon, click on Add an app.

Then you can select the App like below:

Then you can add the site column into any list in your SharePoint site.

And you will be able to see the SharePoint Online list view like below:

Apply SPFx field customizer extension to existing SharePoint list columns

The above approach will work when you will add the site column into any list.

But if you have any existing SharePoint Online list and you want to apply the SPFx field customizer extension to a column, then we can use PowerShell.

By using PnP PowerShell, we can apply the SharePoint Framework (SPFx) field customizer extension to existing list columns in SharePoint Online.

Connect-PnPOnline -Url 'https://tsinfo.sharepoint.com/sites/SPFxTraining/' -Credentials (Get-Credential)
$targetList = Get-PnPList -Identity "Project Status"
$targetField = Get-PnPField -List $targetList -Identity "PercentageCompleted"
$targetField.ClientSideComponentId = "eb51471d-393d-4a5c-b689-158aaca5f84b"
$targetField.Update()
Execute-PnPQuery

Once you open your existing SharePoint list, you will be able to see the formatting.

You may like the following SPFx tutorial:

• no gulpfile found error in spfx
• SPFx – Bind dropdown list from SharePoint list using PnP
• How to add new webpart in spfx solution
• SharePoint framework crud operations no javascript framework
• SPFx SwatchColorPicker Office UI Fabric React Control example

In this SPFx extension tutorial, we discussed how to create and deploy SPFx field customizer in SharePoint Online Office 365.