Category: SPFx

What are SharePoint Online Image Renditions?

Image Renditions were a popular feature in SharePoint On-Premises that automatically generated different image resolutions directly within the system. The advantage of this approach was that optimized images were available for various use cases – for example, smaller thumbnails to avoid loading large original images. This feature not only significantly improved performance by allowing smaller images to load faster in the browser but also reduced network load, which in turn sped up the loading of other resources.

Microsoft provides a module that allows Image Renditions to be requested from the server using JavaScript.

The Image Helper API is part of the module with the same name and must first be integrated into the existing SPFx application.

npm i @microsoft/sp-image-helper

Once the module is installed, the convertToImageUrl function can be used to generate a rendition for a given Image-URL.

import { 
    ImageHelper, 
    IImageHelperRequest 
} from "@microsoft/sp-image-helper";

const renditionSrc = ImageHelper.convertToImageUrl({
    sourceUrl: 'absolute/path/to/image.png',
    width: 1280,
    height: 1024 //optional
});

How does this work?

SharePoint Online generates Image Renditions for images stored within a tenant. Since the API operates synchronously, the requested Rendition seems to already exist when the API is called.

It’s important to note that Renditions are not available for every possible size. Instead, they are generated for a predefined set of image dimensions. When you request a specific size, the API will return the closest available Rendition to match your request.

Using Image Renditions the React-way

To use SharePoint Image Renditions in React, we’ll start by creating a component that encapsulates the Image Rendition API. This will provide us with a reusable and convenient way to work with image renditions.

ImageRendition.tsx

import * as React from "react";
import { useState, useEffect } from "react";
import { 
    ImageHelper, 
    IImageHelperRequest 
} from "@microsoft/sp-image-helper";

type ImageRenditionProps = {
  src: string;
  width?: number;
  height?: number;
  altText?: string;
};

export const ImageRendition = (props: ImageRenditionProps) => {
  const [renditionSrc, setRenditionSrc] = useState<string>("");

  function getRenditionSrc(originSrc: string) {
    if (props.width === undefined || props.width === 0) { 
        return originSrc;
    }

    const opts: IImageHelperRequest = {
      sourceUrl: originSrc,
      width: props.width!,
    };

    if (props.height) {
      opts.height = props.height;
    }
    return ImageHelper.convertToImageUrl(opts);
  }

  useEffect(() => {
    setRenditionSrc(getRenditionSrc(props.src));
  }, [props.src, props.width, props.height]);

  return (
    <img
      src={renditionSrc}
      alt={props.altText}
    />
  );
};

This React component can then be easily used as shown in the following example:

MyComponent.tsx

import { ImageRendition } from "./ImageRendition";

<ImageRendition
    src="https://mytenant.sharepoint.com/Images1/916-4000x3000.jpg"
    width={400}
    height={800}
/>

For a detailed explanation of the Image Rendition API, refer to the official Microsoft article on the topic.
https://learn.microsoft.com/en-us/sharepoint/dev/spfx/image-helper-api