Sitecore Image Parameters

The Sitecore media library stores (per default) all assets (images, documents, …) in its own database rather than on disk. All assets are then streamed using an HttpHandler. All image links goes to an *.ashx handler which then returns the image. You can apply parameters to this handler, allowing you to modify the output (sizing, scaling, …).

The possibility to resize the output is especially useful as you allow users to upload images in any size and still stream the image in the size you need.

Scaled Image

Same image scaled to different sizes.

The example above demonstrates how to get the same uploaded image in different sizes. Sitecore caches the modified image so sizing only has a minor performance impact the first time you request the image.

You can apply parameters directly to the URL.

Here is an example with using an image called “brian.ashx”:
This will give you the original image: http://yourwebsiite/~/media/brian.ashx
This will give you the image with width = 50 px: http://yourwebsiite/~/media/brian.ashx?w=50

The most common parameters are:

  • w = Image width
  • h = Image height
  • as = Allow stretch. Set as=1 to allow image to be larger than original. Set as=0 to disallow image to be upscaled, filling any  space with a color (default is black).
  • bc = The background color of the fill when as=0. bc=000000 is black and bc=ffffff is white.
  • sc = scale image. Use decimal numbers. sc=1 is the original size. sc=1.5 is 150% above normal size.

You can see all parameters here:

If you use XSLT to render your images, you can apply the parameters on the sc:image directly:

<sc:image field="MyImage" width="150" height="100" bc="ffffff"/>

If you use UserControls (.ascx) to render your images, you can register the following tagprefix to access sc:Image and sc:FieldRenderer:

<%@ Register TagPrefix="sc" Namespace="Sitecore.Web.UI.WebControls" Assembly="Sitecore.Kernel" %>

The namespace Sitecore.Web.UI.WebControls contains controls for rendering many different Sitecore types directly, including images.

Unfortunately the The sc:Image only supports MaxWidth, MaxHeight and Scale:

<%@ Control Language="c#" AutoEventWireup="true" TargetSchema="" %>
<%@ Register TagPrefix="sc" Namespace="Sitecore.Web.UI.WebControls" Assembly="Sitecore.Kernel" %>

  <sc:Image ID="image" Field="MyImageField" MaxWidth="100" runat="server" />

But you can use the sc:FieldRenderer and apply the parameters to the Parameters field:

<%@ Control Language="c#" AutoEventWireup="true" TargetSchema="" %>
<%@ Register TagPrefix="sc" Namespace="Sitecore.Web.UI.WebControls" Assembly="Sitecore.Kernel" %>

  <sc:FieldRenderer ID="field" FieldName="MyImageField" Parameters="w=100&h=200&as=1" runat="server" />

About briancaos

Developer at Pentia A/S since 2003. Have developed Web Applications using Sitecore Since Sitecore 4.1.
This entry was posted in .net, c#, Sitecore 6 and tagged , , , , , . Bookmark the permalink.

16 Responses to Sitecore Image Parameters

  1. Bryan says:

    Hey Brian, how do I get Sitecore to NOT put black borders on a scaled-down image? I’ve got an image about 800×400… and I want to display a thumbnail that is 35×35. But my scaled down image keeps the aspect ration, even when I set as=1. Suggestion?

  2. briancaos says:

    Sitecore will only display images in the original aspect ratio, and will therefore add a black border where the ratio does not match.
    Your only option (besides replacing the Sitecore.Resources.Media.ResizeProcessor in the getMediaStream pipeline with your own resizer) is to apply the correct color as background with the “bc” parameter.

  3. Pingback: Sitecore Validators: Validating image width, height and aspect ratio « Brian Pedersen’s Sitecore and .NET Blog

  4. Sean Holmesby says:

    Hey Brian,
    Just wanted to add that our company, Igloo Digital, has a shared source module for image cropping, which is also a handy image parameter. Details here:

  5. Amy says:

    Great article – very helpful! Can you give examples of putting images as backgrounds, and then place Sitecore text fields on top of these? I’m attempting to give a ‘flowchart’ affect to a web page – it would be handy to place vector images in the background – just wondering if this is possible. Thanks!

  6. Kathy H. says:

    Hi Brian,
    I actually have another question that I was hoping you could help me with. I’m new to Sitecore. I have created several news stories for my company’s website. I have included an image with each. When I publish the item, all the text displays but the image does not. What step am I forgetting? I have the image saved in the Media Library.

  7. briancaos says:

    you need to publish the media items as well.

  8. Kathy H. says:

    Thank you for your response. I will make sure that my media items are saved, but I’m confident that I did that step. I’m good to save and publish every change I make. Would you have an additional suggestion for me to check. It seems like most of the pages/content/images have to be saved in at least a couple of locations. My thought was that for the news pages I created and added a published image to, I’m forgetting to publish/activate/etc. in some other location.

  9. Pingback: Create components for Sitecore Page Editor | Brian Pedersen's Sitecore and .NET Blog

  10. Ed G. says:

    Brian, I’m trying to figure out how you set the allow-strech property to default to true for every sitecore media img request? Is there a global setting to tell sitecore to allows create media tags with the as=1 property?

  11. Pingback: Make Sitecore deliver images which fits the screen - Laub plus Co

  12. Pingback: Images not Resizing in Sitecore 7.5, 8.0 | Sean Holmesby

  13. Pingback: Images not Resizing in Sitecore 7.5, Sitecore 8.0 | Sean Holmesby

  14. In Sitecore 7 you can just use the IAR=1 property to disable the aspect ratio. Getting rid of the black borders.

  15. Pingback: Sitecore: Round Image Processor | alexandersmagin

  16. Pingback: Responsive Image Sizing with HTML5 and Sitecore

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s