SPFx Basics: four (4) lesser-known web part manifest properties

Many of the properties in a web part’s manifest file are well known to developers as they’re covered in the SharePoint Framework (SPFx) documentation. For example, the preconfiguredEntries:[] property contains an object of name-value pairs that tell SharePoint what toolbox group users can find the web part, the localized title & description of the web part, and default values in the web part’s public properties. Other properties, like the supportedHosts:[] array specify where web part can be used.

But did you know there are a lot more properties available to you?

In this SharePoint Framework (SPFx) quick tip, I want to focus on some properties in a web part’s manifest file that many people aren’t familiar with.

imageLinkPropertyNames

This property expects an array of strings that contains the names of public properties that are image sources and need to be link fixed up and potentially preloaded for performance reasons.

By including the name of a property that contains an absolute or relative URL to an image in this array, SharePoint will use the Image Helper API to generate the scaled and CDN URL of the image (if available):

{
  ..
  "supportedHosts": ["SharePointWebPart"],
  "supportsThemeVariants": true,
  "imageLinkPropertyNames": ["defaultBannerImage"],
  "preconfiguredEntries": [{
    "properties": {
      "defaultBannerImage": "/sites/mysite/Documents/file_1200x1200.png"
    }
  }]
}

linkPropertyNames

This property expects an array of strings that are links and need to be link fixed up.

Link fixup is a SharePoint feature to help make sure SharePoint internal links in the content are correct. Pages and content can be moved around within SharePoint site hierarchy.

{
  ..
  "supportedHosts": ["SharePointWebPart"],
  "supportsThemeVariants": true,
  "linkPropertyNames": ["referencePage"],
  "preconfiguredEntries": [{
    "properties": {
      "referencePage": "/sites/mysite/Pages/somePage"
    }
  }]
}

searchablePropertyNames

This property expects an array of strings that contains the names of public properties that need to be indexed for search. By default, web part properties aren’t indexed for search, but by adding them to this array, you can index them.

For example, consider if you have a web part that displays the price of various publicly traded stocks. It’s intended to be used on pages that contain research of your competitors.

Maybe the page only contains the company name, like Contoso, but not its stock symbol CONT. Or maybe the page is about Bitcoin but the page contains no mention of its symbol BTC. Wouldn’t it be nice if someone searched for Contoso or Bitcoin to also have the same page show up in the search results if they searched for CONT or BTC?

This web part has a property, stockSymbol, that you can set using the property pane. You can tell SharePoint to include this property in the index so it can be be used in the search results:

{
  ..
  "supportedHosts": ["SharePointWebPart"],
  "supportsThemeVariants": true,
  "searchablePropertyNames": ["stockSymbol"],
  "preconfiguredEntries": [{
    "properties": {
      "stockSymbol": "MSFT"
    }
  }]
}

requiredCapabilities

This property, found on the root object alongside the preconfiguredProperties:[] property, specifies the set of capabilities this web part requires from the host page in order to be usable.

If the host does not support one of the required capabilities, the web part will not be visible in the toolbox.

There are two properties you can specify on this object:

BingMapsKey

This boolean flag indicates if the web part requires the Bing Maps key to be available in the site. The Bing Maps credential key can be used to show the Bing maps control according to a provided coordinate.

To use this, you must first acquire a Bing Maps key and then set it at the tenant level.

To create & obtain a key, see the Microsoft Bing Maps documentation: Getting a Bing Maps Key.

To set the key at the SharePoint site, site collection, or farm level, see the Microsoft SharePoint documentation: Set the Bing Maps key at the web and farm level in SharePoint.

You can also set the key in your SharePoint Online tenant using tenant scoped properties, which can be set using the SharePoint REST API, SPO Management Shell, PnP PowerShell, or the CLI for Microsoft 365. The property must be named BING_MAPS_KEY.

For example, let’s say you have a Bing Maps key of 123456abcdef. To set it for your SPO tenant using the CLI for Microsoft 365, use the following:

m365 login
m365 spo storageentity set --key "BING_MAPS_KEY" --value "123456abcdef"

Now, to make sure the web part only displays this value when they key is present, set the required property in the web part’s manifest:

{
  ..
  "supportedHosts": ["SharePointWebPart"],
  "supportsThemeVariants": true,
  "requiredCapabilities": { "BingMapsKey": true },
  "preconfiguredEntries": [{ .. }]
}

AuthenticationModel

This property accepts an array that indicates the web part requires any of following authentication models to be available in the site.

• OpenIDConnect
• Federated

The authentication model can be used to connect to Microsoft Graph or an Office 365 Connecter.

{
  ..
  "supportedHosts": ["SharePointWebPart"],
  "supportsThemeVariants": true,
  "requiredCapabilities": { "AuthenticationModel": ["OpenIDConnect"] },
  "preconfiguredEntries": [{ .. }]
}