This week some new updates were announced on SharePoint Modern page and image editing capabilities. One of the new capabilities is to crop images on your Modern pages within the Image Web part.

Crop image capability in action using an image web part on a Modern page

Classic image renditions

When people speak about cropping images in SharePoint, a much used capability are Image renditions within the classic publishing feature. This feature has some drawbacks in SharePoint Online as documented by Chris O’Brien and is not available in Modern sites. So I was very curious about how the new crop functionality works within the Image web part on Modern pages.

Image resolutions

As earlier documented by Stefan Bauer, the new Modern sites have new capabilities available on image resolutions. In the background, when an image is uploaded to a library, 6 resolutions are created by SharePoint next to the original. Please read the post by Stefan Bauer, for more information. The image within the Image web part are retrieved through a service called ‘/_layouts/15/getpreview.ashx’. The call to this web part contains some parameters in order to retrieve the correct image. One of the parameters is the resolution to get (0 to 6). The total call to the service used in the Image web part is:


Depending the page size (mobile, tablet, desktop, etc.), another resolution id is used, depending your device or page width/height. So a lower resolution is retrieved on mobile devices.

Cropping an image

When you add an Image web part to a Modern page and select an image to use, the crop capability is available when you click on the image. The following options are available:

Crop options available

When you click on the Aspect ratios button, an additional toolbar will fly out, with options for different predefined aspect ratios (16:9, 3:2, 4:3, and 1:1). There is also an option to rotate the crop box. This way you can choose the aspect ratio orientation. Next to the predefined aspect ratio’s, there is also a free format option.

Free ratio cropping mode

When you are done cropping the image as you like it, click the Save button. The image can always be turned back to its original state by clicking the Reset button.

Final result

The final result is a cropped image on your page. Very nice! The size of the image is always determined by the section it is added to. So if you use a one column section on your page and add an image web part to it, the image is always displayed in full width. So it is very important to use the right section layouts in order to get a descent result.

Screen Shot 2018-01-10 at 11.28.26.png
Same image in different page section column

The actual crop information you used on the image is saved within the page properties itself. The property ‘CanvasContent1’ on the Modern page contains all web parts and within the web part it also holds the crop information.

Screen Shot 2018-01-10 at 11.36.40
The crop information in the CanvasContent1 property

HTML/CSS trick

As we look at the output HTML and CSS for an image in an Image web part, we can see that a HTML/CSS trick is used to actual crop the full image. A div overlay is used on the retrieved resolution.

In the end the Image web part will load the image in the following way:

  1. Determine the image resolution to get, depending the screen/page size;
  2. Get the correct image using the service /_layouts/15/getpreview.ashx using the above resolution;
  3. Get the crop information stored within the web part;
  4. Render the image html in a div container and apply some CSS to the container in with the crop properties in order to only show a cropped part of the image.

HTML/CSS div overlay on the original image with certain resolution

As we look at the loading times of retrieving the images through the service, the actual loading times look very good. So it seems this way of using Image resolutions is a preferred way. This can also be used in your custom SPFx web parts.


In Classic Sites we have the Image Rendition capability in order to crop our images and use them in pages. For Modern Sites a new cropping capability is announced. This cropping is used in combination with Image Resolutions. Image resolutions are created when you upload images in Modern sites. They are retrieved by calling a service. The Image web part will automatically retrieve the correct Image resolution based on the screen size. This way lower resolution images are used on mobile devices. The Image web part itself holds the cropping information you apply to an image and an HTML/CSS trick is used to crop the actual image. The way to retrieve a certain image resolution using a service is a good way in order to retrieve lower resolution variants. This technique can als be used in your custom SPFx web parts.