Skip to content

Placeholder control

This control renders a placeholder which can be used to show a message that the web part still has to be configured.

Placeholder control output

How to use this control in your solutions

  • Check that you installed the @pnp/spfx-controls-react dependency. Check out the getting started page for more information about installing the dependency.
  • Import the following modules to your component:
import { Placeholder } from "@pnp/spfx-controls-react/lib/Placeholder";
  • Use the Placeholder control in your code as follows:
<Placeholder iconName='Edit'
             iconText='Configure your web part'
             description='Please configure the web part.'
             buttonLabel='Configure'
             onConfigure={this._onConfigure}
             theme={this.props.themeVariant} />
  • With custom element for description:
<Placeholder iconName='Edit'
             iconText='Configure your web part'
             description={defaultClassNames => <span className={`${defaultClassNames} ${additionalStyles}`}>Please configure the web part.</span>}
             buttonLabel='Configure'
             onConfigure={this._onConfigure}
             theme={this.props.themeVariant} />
  • With the onConfigure property you can define what it needs to do when you click on the button. Like for example opening the property pane:
private _onConfigure = () => {
  // Context of the web part
  this.props.context.propertyPane.open();
}

Sample of using the hideButton functionality for hiding the button when page is in read mode:

<Placeholder iconName='Edit'
             iconText='Configure your web part'
             description='Please configure the web part.'
             buttonLabel='Configure'
             hideButton={this.props.displayMode === DisplayMode.Read}
             onConfigure={this._onConfigure}
             theme={this.props.themeVariant} />

Sample to only display Placeholder when the web part is in edit mode:

{
  this.displayMode === DisplayMode.Edit ?
  <Placeholder iconName='Edit'
               iconText='Configure your web part'
               description='Please configure the web part.'
               buttonLabel='Configure'
               onConfigure={this._onConfigure}
               theme={this.props.themeVariant} /> :
  <div />
}

Implementation

The placeholder control can be configured with the following properties:

Property Type Required Description
buttonLabel string no Text label to be displayed on the button bellow the description. The button is optional.
contentClassName string no This is the className that is applied to the root element of the content zone. You can use this to apply custom styles to the placeholder.
description string | ((defaultClassNames: string) => React.ReactElement) yes Text description or render function for the placeholder. This appears bellow the Icon and IconText.
iconName string yes The name of the icon that will be used in the placeholder. This is the same name as you can find on the Office UI Fabric icons page: Office UI Fabric icons. For example: Page or Add.
iconText string | ((defaultClassNames: string) => React.ReactElement) yes Heading text or render function which is displayed next to the icon.
hideButton boolean no Specify if you want to hide the button. Default is false.
onConfigure function no onConfigure handler for the button. The button is optional.
theme IPartialTheme | ITheme no Set Fluent UI Theme. If not set or set to null or not defined, the theme passed through context will be used, or the default theme of the page will be loaded.