How to Create Field Customizer Extension

This article walks you through creating a Field Customizer extension for SharePoint using the SharePoint Framework (SPFx). The extension will format a numeric field in a SharePoint list to highlight values with color-coded backgrounds based on specific conditions.

Here’s how to create a Field Customizer extension step-by-step.

Step 1. Create a new HelloWorld extension by running the Yeoman SharePoint Generator.

yo @microsoft/sharepoint

Step 2. When prompted, enter the following values.

What is your solution name?: field-extension
Which type of client-side component to create?: Extension
Which type of client-side extension to create?: Field Customizer
What is your Field Customizer name?: HelloWorld
Which template would you like to use?: No JavaScript Framework

Step 3. To test your extension, you'll need to first create the field to test the customizer. So move to the site in your SharePoint Online tenant where you want to test the field customizer.

Navigate to the Site Contents page.
On the toolbar, select New, and then select List.
Create a new list named Orders, and then select Create.
Select the + sign, and then select Number to create a new Number field for the list. Set the name of the field to Percent, and then select Save.
Add a few items with different numbers in the percent field. We'll modify the rendering later in this tutorial, so the different numbers will be presented differently based on your custom implementation.

Step 4. Within Visual Studio Code, open the ./config/serve.json file.

Set the InternalFieldName attribute to Percent for the field name, which we created. Update the page URL attributes to match the URL of the list that we created in the preview steps. After the changes, your serve.json should look like the following code.

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/spfx-serve.schema.json",
  "port": 4321,
  "https": true,
  "serveConfigurations": {
    "default": {
      "pageUrl": "https://<TenantName>.sharepoint.com/sites/<SiteName>/Lists/Orders/AllItems.aspx",
      "fieldCustomizers": {
        "Percent": {
          "id": "b909e395-f714-421f-94e0-d638dafeb210",
          "properties": {
            "sampleText": "Value"
          }
        }
      }
    },
    "helloWorld": {
      "pageUrl": "https://<TenantName>.sharepoint.com/sites/<SiteName>/Lists/Orders/AllItems.aspx",
      "fieldCustomizers": {
        "Percent": {
          "id": "b909e395-f714-421f-94e0-d638dafeb210",
          "properties": {
            "sampleText": "Value"
          }
        }
      }
    }
  }
}

Step 5. Compile your code and host the compiled files from the local machine by running this command.

gulp serve

Step 6. After successful compilation, Notice how the Percent column values are now presented with an additional prefix string as Value:, which is provided as a property for the Field Customizer.

$Field Customizer\$

Step 7. Let's enhance this some more. Open the ./src/extensions/helloWorld/HelloWorldFieldCustomizer.module.scss file, and update the styling definition as follows.

.HelloWorld {
  .cell {
    display: inline-block;
  }
  
  .full {
    background-color: #e5e5e5;
    width: 100px;
  }
}

Step 8. Open the file ./src/extensions/helloWorld/HelloWorldFieldCustomizer.ts and update the onRenderCell() method as follows.

@override
public onRenderCell(event: IFieldCustomizerCellEventParameters): void {
  event.domElement.classList.add(styles.cell);
  event.domElement.innerHTML = `
    <div class='${styles.HelloWorld}'>
        <div class='${styles.full}'>
        <div style='width: ${event.fieldValue}px; background:#0094ff; color:#c0c0c0'>
              ${event.fieldValue}
        </div>
        </div>
    </div>`;
}

Step 9. Save the code and see how the list looks changed.

A graphical representation of the field value is indicated.

Graphical representation

Note

Use your own GUID and project names where applicable.
You can expand the logic in onRenderCell to fit your specific needs, such as rendering HTML, React components, or icons.

Conclusion

The Field Customizer extension enhances the SharePoint user experience by adding conditional formatting and improving readability in list views. You can further extend this logic to include icons, advanced formatting, or even interactive features.