Web part properties in the SharePoint Framework – part 2

In this post I continue looking at the out-of-the-box controls you can use for web part properties in SPFx. I think the team have done a good job on how web part properties work – in terms of controls, you can always create your own but it’s good to know you often don’t have to. You can represent most things as a web part property - we have dropdowns, checkboxes, sliders, toggles and so on. And as we’ll see here, even the humble button has lots of options.

• In this article:
  • The humble Button – more options than you knew!
  • Toggle, Slider, Choice Group and other controls
• Other articles:
  • Part 1 - Textbox, Dropdown and Checkbox controls, and structuring properties into pages and groups
  • Dynamically fetching options for the Dropdown control
  • Implementing custom controls for web part properties

NOTE – in these articles I provide a description of most important properties of each control (partly based on specific nuances I observe when using them), but be sure to also reference the official docs for those. The main point of my posts is to show the visual screenshot of each control and add some extra tips/info, rather than duplicate the documentation.

Buttons (PropertyPaneButton)

If you need to use a button in the web part property pane, the good news is there are lots to pick from!

What it looks like:

By the way, those lines between each button are there just because I’m using a horizontal rule (PropertyPaneHorizontalRule control) to separate each one – another useful control you can use to help present your web part properties as you like.

Code:

Buttons all share some common properties which are fairly self-explanatory, but note that some properties only apply to some button types. Here are some key ones, but also see ipropertypanebuttonprops for some extra details on the 'aria' properties for use with screen readers.

Properties:

Property	Description
text	Text displayed on the button.
buttonType	Specifies the type of button to show, from PropertyPaneButtonType enum: Normal Primary Hero Compound Command Icon
onClick	Pointer to a function to execute when button is clicked. N.B. There are some additional options in terms of interacting with web part properties and context, see the ‘Buttons and bound properties’ and ‘Context – ‘this’ in click handler’ sections for more details.
icon	Used for Hero and Icon buttons only. Specify a value that matches up with the name of an icon in the Office UI Fabric icon set - https://dev.office.com/fabric#/styles/icons#icons
description	Used for Compund buttons only – displays as the secondary text
disabled	Specifies if the control is disabled.

Other aspects of buttons

Buttons and bound properties

Buttons can be bound to properties of your web part – this is optional, and is done by specifying a value for the first parameter which matches up with a property you have defined (notice it’s an empty string for most buttons in my sample above). I see it as a nice way to hook into state/properties for the web part itself. This can be useful if you need to set a web part property when a button is clicked – perhaps you want to track if the button has ever been clicked so that other controls can be enabled/disabled or some other similar scenario. You could update a property ‘manually’ yourself in code, but the nice thing is that the old value is passed to your onClick handler, and returning a value from the function sets the new value, which makes things simple. The pattern is shown below:

private heroButtonClick(oldVal: any): any {
    if (oldVal === "Something old") {
      // do something..
    }
    return "Something new";
  }

In the larger code sample above showing button declarations, you can see that most buttons are not bound to a property (first parameter is an empty string), but the hero button is bound to a web part property named ‘btnHero’. This is defined in my manifest.json file, and like any web part property, I can set a default value there. If you just need a simple button click handler, you can declare the function without a parameter, and without returning a value.

Context – ‘this’ in click handler

If you specify the click handler in the normal way (e.g. onClick: this.cobWPPropButtonClick), then inside the function ‘this’ will represent the button. This is useful if you want to know which button fired the handler, perhaps because you have multiple buttons sharing the same callback. If for any reason you want ‘this’ to represent the overall web part class, you can bind with onClick: this.wpPropButtonClick.bind(this).

Summary:

• if you want context of button, bind with onClick: this.wpPropButtonClick
• if you want to stay in context of overall class/web part bind with  onClick: this.wpPropButtonClick.bind(this)

Icons

To use one of the button types which use an icon (Hero or Icon button), you reference a named icon in Office UI Fabric. These can be found at https://dev.office.com/fabric#/styles/icons#icons, and there are lots to pick from:

Indeed, I spent a happy 10 minutes amusing myself by creating buttons with some of the more unusual icons

Haha! Anyway, there’s quite a lot of flexibility there and it’s definitely possible to create buttons which lead to a nice user experience. Just don’t go too crazy

Toggle control (PropertyPaneToggle)

The Toggle control is fairly simple, and suits anything boolean-like that can be on or off, enabled or disabled.

What it looks like:

Notice that there are separate labels for the on state and the off state, which show appropriately. If you need some code to execute when the toggle changes state, note that your entire getPropertyPaneConfiguration() method runs at this time – in fact, it does whenever a control changes state in a reactive property pane (but not otherwise). That should be a reminder that you need to keep this method lean, and only do async lookups when absolutely needed, not on every execution.

Code:

Properties:

Property	Description
label	Text displayed next to the control.
onText	Specifies the text to show when in the ‘on’ state.
offText	Specifies the text to show when in the ‘off’ state.
checked	Used to set the state of the toggle.
key	A unique key to identify the control.
disabled	Specifies if the control is disabled.

Slider control (PropertyPaneSlider)

The slider control is perfect when you want to allow a user to select within a range of values (min/max). It’s quite flexible in that you can choose the ‘step’ value, e.g. to go up in increments of 5, 10, or whatever you need.

What it looks like:

Code:

Properties:

Property	Description
label	Text displayed next to the control.
min	Specifies the minimum value (lower bound).
max	Specifies the maximum value (upper bound).
step	Specifies the increment that the value can be increased by when the slider is dragged or clicked.
showValue	If the current value should be shown next to the control (enabled in my image).
value	Specifies the initial value.
disabled	Specifies if the control is disabled.

Choice Group control (PropertyPaneChoiceGroup)

This control allows the user to make a selection, but with radio buttons instead of a dropdown list. It works similar to the DropdownList control in that it takes an array of options. One notable difference here is that if you don’t want plain radio buttons, images can be used too.

What it looks like (radio buttons):

Code (for radio button options shown above):

What it looks like (radio buttons):

Note you can actually specify a different image for when the option is selected compared to when it is not.

Code (for images shown above):

Properties:

Property	Description
label	Text displayed next to the control.
options	The set of IPropertyPaneChoiceGroupOption items to use as the choices.

Properties of the IPropertyPaneChoiceGroupOption:

Property	Description
key	Unique key for the item.
text	Text for the item.
imageSrc	URL of the image to use, when using images rather than radio buttons. (I only tested with absolute URLs so far)
imageSize	An object containing height/width properties to specify the size of the image.
checked	Used to specify if this item is selected.
disabled	Specifies if this item is disabled (not available for selection).

Link control (PropertyPaneLink)

A simple control which allows you to put a link in the web part property pane - could be used to provide a link to some help or guidance for example.

What it looks like:

Code:

Properties:

Property	Description
text	Text for the link.
href	Hyperlink destination.
target	Window to use – options include _self (default), _parent, _top and _blank.
popupWindowProps	An object specifying the width, height, title and position of a pop-up window (IPopupWindowProps).
disabled	Specifies if the link is disabled.

Summary

There are lots of out-of-the-box controls you can use when implementing web part properties in the SharePoint Framework. In this post we looked at the Button, Slider, Toggle, ChoiceGroup and Link controls – but there are others too, including Textbox, Dropdown and Checkbox controls which I wrote about earlier. A big part of providing a usable web part is often the care taken around how the user will set properties, so knowing what’s in the toolbox is important for SharePoint developers.