SPFx Property Controls: Working with PropertyFieldBrandFontPicker

One of the newest controls available in the PnP SPFx Property Controls library is PropertyFieldBrandFontPicker. It allows users to select fonts directly from the Property Pane, making it easy to create web parts that support typography customization without building a custom font selector.

In this article, we’ll build a simple SPFx Web Part that:

• Adds a Brand Font Picker to the Property Pane.
• Displays custom font tokens.
• Stores the selected font in the Web Part properties.
• Passes the selected font to a React component.
• Applies the font dynamically to the rendered content.

Official Documentation

PnP SPFx Property Controls

PropertyFieldBrandFontPicker

SPFx Documentation

Installing the library

Inside your current SPFx solution install the Property Controls package.

npm install @pnp/spfx-property-controls --save --save-exact

To verify the installed version:

npm list @pnp/spfx-property-controls

Web Part Properties

Our Web Part stores only two values.

export interface IPropertyFieldBrandFontPickerWpWebPartProps {
  description: string;
  brandFont: string;
}

Notice that only persistent values belong here.

Do not place callback methods such as:

onPropertyPaneFieldChanged
onSelectionChanged
onPropertyPaneFieldChangedCallback

These methods are part of the Property Pane infrastructure and should never be persisted.

React Component Properties

The React component receives only the information it needs to render.

export interface IPropertyFieldBrandFontPickerWpProps {
  description: string;
  brandFont: string;
}

Keeping the React props clean avoids unnecessary TypeScript errors.

Creating Custom Font Tokens

The control supports custom font definitions using IBrandFontToken.

const customFontTokens: IBrandFontToken[] = [
  {
    name: 'corporateHeading',
    displayName: 'Corporate Heading Font',
    value: '"Montserrat", sans-serif',
    category: 'site'
  },
  {
    name: 'corporateBody',
    displayName: 'Corporate Body Font',
    value: '"Open Sans", sans-serif',
    category: 'site'
  }
];

Each token contains:

Initializing the Web Part

A good practice is to initialize the property with a default value.

protected async onInit(): Promise<void> {
  await super.onInit();
  if (!this.properties.brandFont) {
    this.properties.brandFont = '"Montserrat", sans-serif';
  }
  this._environmentMessage =
    await this._getEnvironmentMessage();
}

This guarantees that the React component always receives a valid font.

Rendering the React Component

The selected font is passed directly to the component.

public render(): void {
  const element =
    React.createElement(
      PropertyFieldBrandFontPickerWp,
      {
        description: this.properties.description,
        brandFont: this.properties.brandFont
      }
    );
  ReactDom.render(element, this.domElement);
}

Adding the Property Control

The control is added inside the Property Pane group.

PropertyFieldBrandFontPicker('brandFont', {
  label: 'Custom Brand Font',
  initialValue: this.properties.brandFont,
  onPropertyChange:
    this.onPropertyPaneFieldChanged.bind(this),
  properties: this.properties,
  context: this.context,
  customFontTokens,
  showPreview: true,
  key: 'brandFontFieldId'
})

Let’s understand each property.

label

The text displayed above the control.

label: 'Custom Brand Font'

initialValue

Defines the currently selected font.

initialValue: this.properties.brandFont

onPropertyChange

This callback updates the Web Part property whenever the user selects another font.

onPropertyChange:
  this.onPropertyPaneFieldChanged.bind(this)

Using bind(this) ensures the callback keeps the correct Web Part context.

properties

Provides access to the Web Part properties.

properties: this.properties

context

The SPFx context required by the control.

context: this.context

customFontTokens

Registers your own font collection.

customFontTokens

showPreview

Displays a live preview of each font inside the picker.

showPreview: true

key

Unique identifier for the Property Pane control.

key: 'brandFontFieldId'

Applying the Selected Font

Inside the React component simply use the CSS fontFamily property.

<h2 style={{ fontFamily: brandFont }}>
  PropertyFieldBrandFontPicker
</h2>
<p style={{ fontFamily: brandFont }}>
  {description}
</p>

Since the control returns a valid CSS font-family string, it can be applied directly.

Property Pane Group

The control lives inside the Property Pane group.

groups: [
  {
    groupName: strings.BasicGroupName,
    groupFields: [
      PropertyPaneTextField(...),
      PropertyFieldBrandFontPicker(...)
    ]
  }
]

The Property Pane will display something similar to:

Basic Settings
Description
_____________________
Custom Brand Font
▼

A Version Compatibility Note

While building this sample we found an interesting behavior.

The official documentation currently demonstrates the control using an onSelectionChanged callback.

However, depending on the version of @pnp/spfx-property-controls installed in your project, the TypeScript interface may instead require:

onPropertyChange
properties

Attempting to use onSelectionChanged with that version results in a compilation error because the installed interface does not expose that property.

The lesson is simple:

Always trust the TypeScript definitions that ship with the package version installed in your project. Documentation may describe a newer API than the one available in your solution.

Checking the installed version can save a lot of debugging time.

npm list @pnp/spfx-property-controls

Common Issues

TypeScript complains about missing callbacks

If you see errors similar to:

Type is missing the following properties...

Verify that your React component interface contains only:

description
brandFont

Do not expose Property Pane callbacks as React props.

Font doesn’t change

Verify that your React component applies:

style={{ fontFamily: brandFont }}

Font isn’t available

Adding

value: '"Montserrat", sans-serif'

does not install the font.

The browser must already have access to that font through CSS, Microsoft 365 branding, or another supported source.

Otherwise the browser will fall back to:

sans-serif

Final Thoughts

PropertyFieldBrandFontPicker is an excellent addition to the PnP SPFx Property Controls library. It provides a simple way to expose typography settings directly in the Property Pane while keeping the implementation clean and strongly typed.

Combined with custom font tokens, it becomes a powerful option for building branded SharePoint experiences without writing your own font picker component.

References

PnP SPFx Property Controls

PropertyFieldBrandFontPicker

SharePoint Framework Documentation