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 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
sharepoint framework extension field customizer

Then run the Yeoman SharePoint Generator.

yo @microsoft/sharepoint
SharePoint Framework (SPFX) Extensions

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)
spfx field customizer examples

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

Build your first Field Customizer

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

SPFx extensions Field Customizer

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

code .

You can check the solution looks like below:

Create SPFx Field Customizer Extension

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:

How to Create SPFx Field Customizer Extension

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:

Create and Deploy SharePoint Framework extension

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:

deploy spfx Field Customizer

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

sharepoint framework extension field customizer

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.

spfx extension field customizer

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

spfx extension deployment

Click on Deploy.

You can see the it is deployed successfully.

how to deploy SPFx extensions

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

Then you can select the App like below:

how to deploy SPFx extensions sharepoint online

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:

sharepoint framework extension field customizer

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:

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

>