Placeholder Control in SPFx (PnP React Controls)

The Placeholder control is a simple but very useful UI helper from PnP when your web part still has no configuration.

It provides a clean “empty state” experience, guiding the user to open the Property Pane and configure the web part.

This is extremely common in professional SharePoint Framework development.

Why use Placeholder?

Without Placeholder:

• User adds the web part
• The web part appears blank
• User doesn’t know what to do

With Placeholder:

• User sees instructions
• A configure button appears
• Clicking it opens the Property Pane

This improves UX significantly.

Official Documentation

PnP Control:

PnP Placeholder Documentation

Related control (you linked RichText by mistake):

PnP RichText Documentation

SPFx official docs:

SPFx Web Parts Overview

Fluent UI:

Fluent UI React

Installation

Inside your SPFx solution:

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

Component Code

PlaceholderWp.tsx

import * as React from 'react';
import { Placeholder } from "@pnp/spfx-controls-react/lib/Placeholder";
import { IPlaceholderWpProps } from './IPlaceholderWpProps';
const PlaceholderWp: React.FC<IPlaceholderWpProps> = ({ context }) => {
  const _onConfigure = () => {
    context.propertyPane.open();
  };
  return (
    <Placeholder
      iconName='Edit'
      iconText='Configure your web part'
      description='Please configure the web part.'
      buttonLabel='Configure'
      onConfigure={_onConfigure}
    />
  );
};
export default PlaceholderWp;

Props Interface

IPlaceholderWpProps.ts

import { WebPartContext } from "@microsoft/sp-webpart-base";
export interface IPlaceholderWpProps {
  context: WebPartContext;
}

How it works

Importing Placeholder

import { Placeholder } from "@pnp/spfx-controls-react/lib/Placeholder";

This loads the PnP control.

Opening the Property Pane

context.propertyPane.open();

This is the most important part.

The Placeholder button executes:

onConfigure={_onConfigure}

which opens the SPFx Property Pane.

Placeholder Properties

Understanding iconName

This uses Fluent UI icons.

Example:

iconName='Edit'

Other examples:

iconName='Settings'
iconName='Add'
iconName='EditNote'
iconName='Document'

Icons come from Fluent UI.

Typical real-world scenario

Example:

A web part that needs:

• List Name
• Site URL
• Filter
• Display mode

Before configuration:

Show Placeholder.

After configuration:

Render actual content.

Pattern:

return !configured ? (
  <Placeholder ... />
) : (
  <ActualComponent />
);

This is one of the most common SPFx patterns.

Conditional Placeholder Pattern (recommended)

Example:

return (
  !listName ? (
    <Placeholder
      iconName='Edit'
      iconText='Configure this web part'
      description='Select a list first.'
      buttonLabel='Configure'
      onConfigure={_onConfigure}
    />
  ) : (
    <div>Web Part Loaded</div>
  )
);

This is the production pattern.

Benefits

Using Placeholder gives:

✔ Better onboarding
✔ Better UX
✔ Cleaner empty states
✔ Clear action path
✔ Less user confusion
✔ Standardized configuration flow

Final Thoughts

The Placeholder control is simple, but it is one of the most important UX controls in the entire SharePoint Framework ecosystem.

Many enterprise web parts use this exact pattern.

If your web part depends on configuration, this should almost always be your first render state.