Use Image Helper API with the SharePoint Framework (beta)

Context

With the SharePoint Framework v1.14 release, Microsoft introduced a brand new Image Helper API to help developers to manage thumbnail images and optimized URLs to images stored in the SharePoint Online service. This feature is actually in developer preview and shouldn’t be used in production until the GA release planned for June 2022 (subject to change). In this first article of 2022, I’ll show you how to take advantage of this new developer API in your SPFx solutions so let’s go!

Prerequisites

Once your SPFx solution is scaffolded, you need to install the package from npm with the following command:

npm install @microsoft/sp-image-helper

Note: this package is not part of the default packages installed with the Yeoman SharePoint generator.

After the npm package installation in your SPFx solution, you need to import ImageHelper from the package where you want to use the API as below:

import { ImageHelper } from '@microsoft/sp-image-helper';

Image Helper API usage

Now you are ready to use the API in your SPFx solution. To do this, you need to use the convertToImageUrl() static method from the package which accept a single argument of type IImageHelperRequest:

    const srcImageUrl = "/sites/dev/Shared%20Documents/surface-laptop-studio-workstation_.jpg";
    
    const optimizedImageUrl = ImageHelper.convertToImageUrl(
      {
        sourceUrl: srcImageUrl,
        width: 200
      }
    );

This static method will convert a source URL to a file or page on SharePoint Online into an optimized image URL as a result. In my context, the result URL returned by this method will be something like this:

https://<TENANT_URL>/_api/v2.1/shares/u!aHR0cHM6Ly95aGFiZXJzYWF0LnNoYXJlcG9pbnQuY29tL3NpdGVzL2Rldi9TaGFyZWQlMjBEb2N1bWVudHMvc3VyZmFjZS1sYXB0b3Atc3R1ZGlvLXdvcmtzdGF0aW9uXy5qcGc/driveItem/thumbnails/0/c400x99999/content?preferNoRedirect=true&prefer=extendCacheMaxAge&clientType=modernWebPart

The actual image resolutions supported by the SharePoint Online service are (in pixels): 200, 400, 960, 1600, & 2560. In the case you specify another value in your solution, the service will pick the nearest largest resolution based on the list above.

The great thing with this API is that you can also work with page thumbnail images as below:

    const pageUrl = "/SitePages/People-Directory.aspx";

    const pageThumbnailImage = ImageHelper.convertToImageUrl(
      {
        sourceUrl: pageUrl,
        width: 200
      }
    );

In my context, the result URL returned by the API will be something like this:

https://<TENANT_URL>/_api/v2.1/shares/u!aHR0cHM6Ly95aGFiZXJzYWF0LnNoYXJlcG9pbnQuY29tL1NpdGVQYWdlcy9QZW9wbGUtRGlyZWN0b3J5LmFzcHg/driveItem/thumbnails/0/c960x99999/content?preferNoRedirect=true&prefer=extendCacheMaxAge&clientType=modernWebPart

This result URL will redirect to the private CDN of your tenant:

https://media.akamai.odsp.cdn.office.net/<TENANT_URL>/_layouts/15/images/sitepagethumbnail.png

The conditions to use the private CDN of your tenant are as below:

The private CDN feature must be enabled
The source file must be available within an origin to the CDN
SharePoint Online’s server-side preprocessing must know that the web part property is an image property

So you need to provide the properties where image URLs are stored directly in your solution manifest file with the imageLinkPropertyNames like this:

  "supportedHosts": ["SharePointWebPart", "TeamsPersonalApp", "TeamsTab", "SharePointFullPage"],
  "imageLinkPropertyNames": ["srcImageUrl"],
  "supportsThemeVariants": true,

  "preconfiguredEntries": [{
    "groupId": "5c03119e-3074-46fd-976b-c60198311f70", // Other
    "group": { "default": "Other" },
    "title": { "default": "Image Helper API Demo" },
    "description": { "default": "Image Helper API Demo description" },
    "officeFabricIconFontName": "Page",
    "properties": {
      "srcImageUrl": "/sites/dev/Shared%20Documents/surface-laptop-studio-workstation_.jpg"
    }
  }]

This will make SharePoint Online service aware of these image properties.

I hope this article will help you to start with the brand new Image Helper API and feel free to reach me out if you have any question regarding this topic.

Happy coding everyone!