PropertyFieldIconPicker – Let Users Choose Fluent UI Icons in SPFx

The PropertyFieldIconPicker is one of the most useful controls available in the PnP SPFx Property Controls library. Instead of asking users to manually type the name of a Fluent UI icon, this control displays an interactive picker where they can browse, search, and select icons visually.

It is especially useful for configurable Web Parts that display buttons, cards, menus, navigation items, dashboards, quick links, or any UI element that benefits from customizable icons.

Official Documentation

PropertyFieldIconPicker

PnP SPFx Property Controls

Installing the Control

Install the Property Controls package if it is not already available in your project.

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

Import

Import the control into your Web Part.

import {
  PropertyFieldIconPicker
} from '@pnp/spfx-property-controls/lib/PropertyFieldIconPicker';

Property

Create a property that stores the selected icon.

export interface IPropertyFieldIconPickerWpWebPartProps {
  description: string;
  iconPicker: string;
}

The control stores the icon name as a string.

Example:

Home
Add
Mail
Calendar
People
World
Download
Settings

Adding the Control to the Property Pane

Add the picker inside the Property Pane.

PropertyFieldIconPicker('iconPicker', {
  currentIcon: this.properties.iconPicker,
  key: 'iconPickerFieldId',
  buttonLabel: 'Select icon',
  label: 'Icon Picker',
  renderOption: 'panel',
  properties: this.properties,
  onPropertyChange: this.onPropertyPaneFieldChanged.bind(this),
  onChanged: (iconName: string) => {
    this.properties.iconPicker = iconName;
  },
  onSave: (iconName: string) => {
    this.properties.iconPicker = iconName;
    this.render();
  }
})

Property Pane Group

The control can be combined with any other Property Pane controls.

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

Rendering the Selected Icon

The PropertyFieldIconPicker only returns the icon name.

Rendering the icon is your responsibility.

Using Fluent UI:

import { Icon } from '@fluentui/react';

<Icon iconName={props.iconPicker} />

Example with a larger icon:

<Icon
  iconName={props.iconPicker}
  styles={{
    root: {
      fontSize: 48
    }
  }}
/>

What Does the Control Return?

Unlike controls such as List Picker or People Picker, this control returns a simple string.

Example:

"Mail"

or

"Home"

or

"Settings"

This makes it extremely easy to save and reuse.

Typical Use Cases

The control is ideal for:

• Navigation menus
• Dashboard tiles
• Quick Links
• Hero components
• Buttons
• Cards
• Status indicators
• Custom menus
• Command bars
• Settings pages

Render Options

The picker supports different display modes.

The most commonly used option is:

renderOption: "panel"

which opens a searchable Fluent UI panel containing hundreds of available icons.

Advantages

Compared to a regular text field, the Icon Picker provides several advantages.

• Visual icon selection
• Search support
• No need to memorize icon names
• Reduces typing mistakes
• Better user experience
• Works directly with Fluent UI Icons

Things to Know

The control stores only the icon name.

It does not store:

• SVG
• Image
• Font
• Base64
• Unicode value

Only the Fluent UI icon identifier is persisted.

Example Flow

The typical execution flow is straightforward.

1. The user opens the Property Pane.
2. The Icon Picker panel opens.
3. The user searches for an icon.
4. The user selects the icon.
5. The control returns the icon name.
6. The property is updated.
7. The Web Part renders the selected icon.

Best Practices

• Store only the icon name.
• Use the Fluent UI Icon component for rendering.
• Provide a default icon when no selection exists.
• Use meaningful labels for the Property Pane.
• Group icon-related settings together.
• Keep the picker inside the Basic Settings group unless there is a dedicated Appearance section.

Limitations

Some considerations when using this control:

• It only supports Fluent UI icons.
• It does not upload custom SVG files.
• It does not browse image libraries.
• It is intended for icon selection only.

Final Thoughts

The PropertyFieldIconPicker greatly improves the configuration experience of SPFx Web Parts by allowing users to choose Fluent UI icons through a visual interface instead of manually typing icon names.

Because it stores only a simple string, it integrates naturally with Fluent UI components while keeping Web Part properties lightweight and easy to maintain.

For Web Parts that expose configurable buttons, navigation elements, dashboards, or cards, this control is one of the simplest ways to deliver a more polished and user-friendly configuration experience.

References

PropertyFieldIconPicker

PnP SPFx Property Controls