Applies To: SharePoint Framework
When you create a SharePoint Framework (SPFx) webpart, you can customize the icon displayed in the Authoring Canvas Toolbox. Here’s what it looks like by default:
By default, the Office Fabric Page icon is used but this can and should be changed before packaging up your app. This makes sure your webpart doesn’t get lost among all the other webparts and is a very simple way to add a professional touch.
There are 2 ways to customize this icon. You can specify the name of an icon from the Office UI Fabric icons or you can provide a URL to a custom image.
Both of these are accomplished by editing your webpart’s manifest.json file and changing a simple property.
Office UI Fabric Icon
The easiest way to customize your icon is to simply specify the name of an icon class in the Office UI Fabric. You can find all the icons here: https://dev.office.com/fabric#/styles/icons
The Page icon shown above is doing exactly this. You can find this setting in the src/webparts/[YOURWEBPARTNAME]/[YOURWEBPARTNAME].manifest.json file in the preconfiguredEntries/officeFabricIconFontName property:
You can simply change this value from Page to any of the available icon names. Here’s what it looks like with a value of Emoji2:
Keep in mind that this value is CASE SENSITIVE. Also, note that changes to your manifest file (unlike your code files) will require you to stop the gulp serve command and do it again to have those changes reflected in the workbench.
If you inspect the actual toolbox you’ll see that the class name for the span is simply concatenating “ms-Icon–“ and the property value:
This approach is super easy (just change the name) and ensures your webpart matches the official Office styles. But what if you want your own custom icon or logo?
There is another property available called preconfiguredEntries/iconImageUrl and allows you to specify an image URL.
In order to use this property, create a 40x28px icon and upload it somewhere. For this example I’m just going to use my blog, but ideally you would include it in the webpart and then pull this value from your CDN.
You’ll also have to remove the preconfiguredEntries/officeFabricFontIconName property (or the iconImageUrl will be ignored). Here’s what my property looks like:
Again, note that changes to your manifest file (unlike your code files) will require you to stop the gulp serve command and do it again to have those changes reflected in the workbench.
So here’s what it looks like in my local workbench:
What happened!?! For whatever reason, the local workbench continues to try and use a class icon as seen above (You can even see it sets a class of ms-Icon–undefined). However, the O365 workbench (/_layouts/15/workbench.aspx) works just fine:
A quick inspection shows that the property value is just being inserted as the src attribute for an img tag.
This means (and I’m not suggesting you should) that if you happen to have a weird Christopher Walken eyeball gif:
You could simply resize it and get something like this:
Looking at the documentation for the manifest properties (json schema) you may see some
misleading outdated information. (If you haven’t setup config file intellisense in VSCode, go do it now! Here’s an awesome guide.)
The description for the officeFabricIconFontName property looks like this:
It directs you to a site with 600+ icons many of which are present in the UI Fabric Icon styles. However, these names do NOT often match the actual class names and so cannot be reliably depended on to locate your icons (for example, the “Emoji2” icon we used in the sample above is listed as “smiley2” on the font site. It took going to the Office UI Fabric Icons page to find the correct class name).
The description for the iconImageUrl property looks like this:
You are instructed to use an icon that is exactly 38x38px. This is no longer accurate. You can use whatever size you want but it will be scaled to 40x28px.
4 thoughts on “Setting Your SharePoint Framework WebPart Icon”
[…] I showed you how to set your WebPart Icon (the image used in the authoring canvas toolbox). But there is another image, called the App Icon […]
Chris – Do you know what the icon specifications are when working with List View Command Sets? (SharePoint Framework Extensions).
I’m having a few issues creating a command with an icon that responds the same way commands do in the UI in terms of scaling/visibility. Thanks!
Currently, the SPFx ListView Command Sets are in preview and there is a bug with command set images:
So, you should be able to use absolute addresses from your CDN (I have not tried this). I believe these images are 16x16px.
I have opened an issue suggesting that they allow the use of Office UI Fabric icons (same way they do for the webpart icon as shown in this post): https://github.com/SharePoint/sp-dev-docs/issues/642. This is also how OOTB commands are displayed (which is why they scale and respond correctly).
Hi and thanks for the great post.
One question for you: If I want the icon png file to be a part of the code base itself (for example in an assets folder next to my components folder), how do I refer to it in the .json file?