DEV Community

Guido Zambarda
Guido Zambarda

Posted on • Originally published at iamguidozam.blog on

How to Use Image Helper API in SharePoint Framework

#spfx #react #api

Introduction

The Image Helper API has been introduced with the version 1.14 of the SharePoint Framework and it allow to generate a URL to an image that will be close to requested site, this can be useful if resizing operations are required, and also the image might load faster because of caching. To use the Image Helper API the source image will have to be stored in SharePoint Online.

Currently, if the requested width is not one of the supported values, the resulting image may be of a different dimension. The documentation states that the supported widths (in pixels) are the following:

  • 200
  • 400
  • 960
  • 1600
  • 2560

As usual, I’ve created a sample solution to demonstrate how the Image Helper API works, you can find it here.

Visual appearance

The visual appearance of the solution is as follows:

At the top there’s a width selector with some default values, right after it there’s the PnP ImagePicker control. This control will help users selecting the images provided out-of-the-box or the ones from the SharePoint Online sites available to the user.

The last section, will show the processed image and the resulting URL retrieved from the call to the ImageHelper.convertToImageUrl function.

To show the result, here is an example with a default image that is resized to the 400px width:

As you can see the generated SharePoint URL contains many parameters and settings. For example, in the above screenshot, the URL has the following structure:

https://<tenant>.sharepoint.com/_api/v2.1/shares/<drive id>/driveItem/thumbnails/0/c400x99999/content?prefer=noRedirect,extendCacheMaxAge&clientType=modernWebPart&format=webp
Enter fullscreen mode Exit fullscreen mode

In the URL, the section that is defining the size of the generated image is the c400x99999 string. This string specify to the API what’s the desired width and height of the image. The 400 value is the one specified via the dropdown of the sample solution, the 99999 value is specified because no desired height has been specified when calling the convertToImageUrl function.

Show me the code

To use the convertToImageUrl method from the ImageHelper class you will first have to import the SPFx package:

import { ImageHelper } from '@microsoft/sp-image-helper';
Enter fullscreen mode Exit fullscreen mode

The package should already be available when you create the solution, if that’s not the case you can install it with the following command:

npm install @microsoft/sp-image-helper
Enter fullscreen mode Exit fullscreen mode

To quickly allow the picture selection I’ve used the ImagePicker from the PnP reusable React controls.

If you don’t know the PnP reusable React controls package already you can have a look at the official site here.

To actually resize the image with the ImageHelper class you can use the following code:

ImageHelper.convertToImageUrl({ sourceUrl: imageUrl, width: selectedWidth })
Enter fullscreen mode Exit fullscreen mode

The method accepts an object where it’s possible to specify:

  • sourceUrl of the original image, this is a required parameter.
  • width representing the wanted image size, this is also a required parameter.
  • height which is the desired image height, this is an optional parameter and is suggested, if possible, to avoid it for performance reasons.

Conclusions

The Image Helper API is an out-of-the-box functionality that may be of use if you need to show and resize images, that come from SharePoint Online, in your SharePoint Framework solution. It’s easy and straightforward to use. The only downside, in my opinion, is that not always the requested size is the final size of the image so be aware of this possibility.

If you’re interested in knowing more about this you can check the official documentation here.

Hope this helps!

Top comments (0)