First draft


User level: Site Owner; Site Administrator; Editor; Author; Contributor

media library images

Expand All

Understanding how Mosaic crops and re-frames images is useful to understand which type and size of image will work best on your website.


When an editor selects an item style for using with a Grid, List, Carousel etc., Mosaic makes a crop of the List Images of the content included in the widget, taken from the original images uploaded into the media library. The crop is nearly always landscape and will aim to centre the cropped image over the crosshair the editor set on the image when uploading it. The exact size depends on the item style selected.

How well this looks on your page depends on:

  • whether the original image was portrait or landscape
  • how big the original image is in relation to the crop size
  • where the crosshair was set

The closer the crosshair is to the edge of the image, the worse the result is likely to be. This is because the crop can't put the crosshair in the centre of the cropped image, if part of it would then have to fall outside the edge of the original image (see Fig. 2 below).


It is often a user-configurable option to decide how many items per row to include in a Grid or Carousel, or to choose to put a List in a narrow or wide region of a page. Mosaic therefore has to be able to resize the item images to fit all of these uses, whether the editor selects 2 items per row or 6, or uses a wide or narrow region. This means the width of the image can be very different in different widget items: sometimes it may be landscape, but it can often be portrait - as for many items per row or in narrow regions.

Mosaic also provides versions of the image for responsive use: i.e. the same items in the same list will show images of different aspect ratios depending on whether it is viewed on a desktop, tablet or smartphone.

The way it does this is to re-frame the cropped image using an appropriate aspect ratio for the selected options/context to show only the part of the image within the frame. It makes the frame on the basis of the centre of the cropped image.


illustration of portrait image cropping and framing

Fig. 1 Portrait image



Blue box = original portrait image

Green box = cropped with crosshair in the centre

Red box = portrait frame in centre of cropped image - size varies depending on context


illustration of landscape image cropping and framing

Fig. 2 Landscape image



Blue box = original landscape image

Solid green box = cropped with crosshair as near to the centre as possible

Dashed green box = where the cropped image would have been if the original image extended sufficiently on the right-hand side to allow the whole cropped image to fit within it when centred on the crosshair

Solid red box = portrait frame in centre of cropped image - size varies depending on context

Dashed red box = where the framed image  would have been if the cropped image fitted within the original when centred on the crosshair

example image in grid

Fig. 3 Example of an image displaying in a Grid listing item


The blue overlay shows the initial crop size for images used in a Grid listing. The viewport (red frame) then reframes the image responsively, depending on the number of items per row. The cropped image is much wider than the portion of it that shows within the frame, allowing the responsive design to show more of it when fewer items per row fit on the page.

Tips for working with List Images

Applying the following tips will usually help to achieve a good result:

  • have the focal point of the image as close to the centre of the original as possible
  • show the less important part of the image to the left and right of the main part of the image and have sufficient space there for the reframing to find the centre of the image
  • use a larger original image which is more 'zoomed-out' than you would otherwise make it, so that the key part of the image is smaller within the overall size
  • use a large enough image: at least 1600 px wide for a Banner, or 800 px for a Grid or List image
  • use a landscape image
ideal focal point and framing area for a landscape image

Fig. 4 Image with focal point and area most likely to remain uncropped when viewed in a Grid listing

Certain combinations of item styles/widgets/nos. per row can be less than ideal for images that don't fit the optimal layout (especially when using Grids, where there are many options/contexts). If you need to use an image that does not fit this layout, there are some options:

  • select different configuration options, e.g. use 3 or 4 items per row rather than 6
  • select a different item style if there is an option that works better
  • instead of using a filtered or selected list, which uses the content's List Image, build the widget statically and use a separate version of the image optimised for the context where it will appear
  • accept that it won't look ideal in all locations


List of site pages