SPFx Property Controls: Getting Started with PropertyFieldBrandFontPicker

The PropertyFieldBrandFontPicker control is one of the newest additions to the PnP SPFx Property Controls library. It provides a modern font picker that integrates directly into the SharePoint Framework Property Pane, allowing users to select typography without creating a custom configuration experience.

In this article, we’ll build the simplest possible implementation using the default behavior of the control, without custom font tokens.

The Web Part will:

• Add a Brand Font Picker to the Property Pane.
• Store the selected font.
• Pass the selected font to a React component.
• Apply the selected font dynamically.

Official Documentation

PnP SPFx Property Controls

PropertyFieldBrandFontPicker

SharePoint Framework

Installing the Property Controls library

Install the library inside your SPFx solution.

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

Verify the installed version.

npm list @pnp/spfx-property-controls

Web Part Properties

The selected font will be stored in the Web Part properties.

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

Only persistent values belong in this interface.

React Component Properties

The React component only needs the values used during rendering.

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

Keeping this interface simple helps avoid unnecessary TypeScript errors.

Initializing the Property

A good practice is assigning a default value when the Web Part is initialized.

protected async onInit(): Promise<void> {
  await super.onInit();
  if (!this.properties.brandFont) {
    this.properties.brandFont = 'inherit';
  }
  this._environmentMessage =
    await this._getEnvironmentMessage();
}

Using "inherit" allows the Web Part to initially follow the site’s typography.

Rendering the React Component

The selected font is passed directly to the React 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

Inside the Property Pane group, add the control.

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

Notice that no custom font collection is required.

The control will use the fonts available in the current Microsoft 365 branding experience.

Understanding Each Property

label

Defines the text displayed in the Property Pane.

label: 'Brand Font'

initialValue

Specifies the current font.

initialValue: this.properties.brandFont

onPropertyChange

Updates the Web Part property whenever a new font is selected.

onPropertyChange:
  this.onPropertyPaneFieldChanged.bind(this)

The bind(this) ensures that the callback executes in the Web Part context.

properties

Provides access to the current Web Part properties.

properties: this.properties

context

Supplies the SharePoint Framework context required by the control.

context: this.context

showPreview

Displays a live preview while selecting fonts.

showPreview: true

key

Unique identifier of the Property Pane control.

key: 'brandFontFieldId'

Property Pane Group

The control is placed inside a Property Pane group.

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

The Property Pane will look similar to:

Basic Settings
Description
_________________
Brand Font
▼

Applying the Selected Font

Inside the React component simply apply the value using CSS.

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

Since the selected value is already a valid CSS font-family, no additional conversion is required.

How the Flow Works

User selects a font
          │
          ▼
PropertyFieldBrandFontPicker
          │
          ▼
this.properties.brandFont
          │
          ▼
render()
          │
          ▼
React Component
          │
          ▼
fontFamily CSS

Common Issues

Property doesn’t update

Ensure the control includes:

onPropertyChange:
    this.onPropertyPaneFieldChanged.bind(this)

and

properties: this.properties

React component reports missing properties

The React props interface should contain only:

description
brandFont

Do not include Property Pane callback methods.

Selected font is not visible

Verify that your component uses:

style={{ fontFamily: brandFont }}

Font falls back to another font

The control returns a CSS font-family string.

If the selected font is unavailable on the client machine or not provided by Microsoft 365 branding, the browser will automatically use the fallback font.

Final Thoughts

PropertyFieldBrandFontPicker is a very lightweight Property Control that brings typography customization directly into the SharePoint Framework Property Pane.

Even without custom font tokens, it offers an elegant user experience and integrates naturally with Microsoft 365 branding. For most scenarios, this basic implementation is sufficient and requires only a few lines of code.

As your solution evolves, you can later extend this implementation with custom font tokens to provide corporate typography or organization-specific branding.

References

PnP SPFx Property Controls

PropertyFieldBrandFontPicker

SharePoint Framework