Requesting images with specified width/height in SharePoint 2013 with the query string (image renditions)

Image renditions are a powerful new SharePoint 2013 feature which allow not only users to specify the size of an image when adding one to a page, but also for developers to request a specified size in code.

I'm not going to go over image renditions in too much detail as it's covered pretty well on other blogs, such as this one by Waldek Mastykarz. Bascically you set up an image size (e.g. Banner Image – Width: 750px, Height: 120px) in the image renditions list, this is displayed as an option to the user when adding an image to a page. The user can drag the rendition size around the image (like when cropping a profile image in FaceBook).

For developers this gives us a few new tools to work with to help with performance and usability/governance

Setting Renditions

When adding an RichImageField to a page layout, you can specify the default rendition ID, this means the user can't change the rendition. This would be useful for pages where an image always needs to be a certain size (such as a news banner).

You can do this through SharePoint Design Manager in the snippets screen by entering either some dimensions or the rendition ID into the "Rendition Properties". This will generate the snippet to put in your .html page layout file.

image rendition properties example in snippets

If you are using .aspx files instead of Design Manager files, simply add the following properties to your image fields markup:
<%@Register Tagprefix="PageFieldRichImageField" Namespace="Microsoft.SharePoint.Publishing.WebControls" Assembly="Microsoft.SharePoint.Publishing, Version=, Culture=neutral, PublicKeyToken=71e9bce111e9429c"%>
<PageFieldRichImageField:RichImageField runat="server" FieldName="942cf913-d3ad-4493-9754-e91cf53e3cd9" RenditionId="1">

edit image rendition not avilable as set by control
As you can see, the Image Rendition is set to rendition ID 1 and the user can't change this. The one issue with this, is that the user can't crop the image.


<PageFieldRichImageField:RichImageField runat="server" FieldName="942cf913-d3ad-4493-9754-e91cf53e3cd9" DisplayHeight="100" DisplayWidth="100" RenditionId="-1">

Setting the display width and height on the field sets the size settings to disabled on the image screen for the user. It also leaves the rendition options open for the user to select. Regardless of the image rendition the user chooses, it will be added to the page as the specified width and height, in this case 200 x 200. The user can then change the rendition post adding to the page. This could be a good option if you want to force the image to a certain size, but still give the user the option to change it later. It seems a little confusing though, the user would wonder why the rendition field is still enabled initially when it isn't used.

specify height on rendition image field

Query String

Performance wise, this gives us the ability to request images by specific rendition ID OR by width/height. This is awesome!! Images will now be generated at the specified size server side, meaning users aren't downloading large images unnecessarily. Great for mobile sites.

Recently I was coding a news widget for a client using REST calls to the search service. I had to display the first image in all announcements posts. The problem I encountered was some images being returned were pretty massive and caused the widget to load slowly. Lukily, using renditions I was able to overcome the issue by appending the size I required to the query string. Here's an example of an image's src:


For SharePoint online, this all just works. For on premises, you will need to enable the blog cache.


2 thoughts on “Requesting images with specified width/height in SharePoint 2013 with the query string (image renditions)

  1. erick

    I don not see how you are making a rest call to get the image rendition.  I tried many ways however this does not work


Leave a Reply

Your email address will not be published. Required fields are marked *