ImageLoader

​Squarespace comes with a number of built-in facilities for managing images that are uploaded to our system. After uploading an image into a collection, Squarespace automatically resizes image assets into multiple sizes. Our image loader will then help render images properly when they are presented on a page, even on retina displays.

The ImageLoader can also be used to fit or fill an image inside ​a parent container, where it automatically determines which image size to use depending on the current dimensions of the container.

ImageLoader Basics

To eliminate having to guess the appropriate size of an image at load time, you can instead use the Squarespace ImageLoader formatter. Within your template, in the context of an item on our system that is an image, using:

<img {@|image-meta} />

will output an  tag that has various Squarespace data embedded in the image tag, including dimensions, focal point, and a CDN-ready URL.

By using this syntax, when the page loads, our imageLoader will inspect the image element and inject the appropriate size image. This allows you use specify properties like height="X", width="X" or CSS on the image. The loader will inspect the tag and always load the appropriate image size.

Bypassing ImageLoader

If you would like to load one of these image sizes explicitly, use the following syntax from within an image context:

<img src="{assetUrl}?format=300w" />

In this case, the image will be the 300w image. Note that this syntax bypasses our imageLoader, and is not recommended for general use. The available image sizes are:

original, 1500w, 1000w, 750w, 500w, 300w, 100w

Collection/Item Thumbnails

In Squarespace, all Collections and Items can have a thumbnail image associated with them. Sometimes this thumbnail will be implicitly chosen, as is the case with an image item, and sometimes this thumbnail must be explicitly added, as is the case with Collections.

{.main-image?}
<img {@|image-meta} />
{.or}
<img src="/assets/default-image.png" />
{.end}

Using the above {@|image-meta} formatter with a collection will return its thumbnail:

Cropping with Content Fit and Content Fill

The Squarespace ImageLoader can also handle cropping of an image around a focal point. In CSS you can use background-size: cover and background-size: contain to tell a background image to fill or fit its element. With the ImageLoader we achieve the same behavior and get the benefits of loading the correct size image by adding a container element.

For instance:

<div class="content-fit">
<img {@|image-meta} />
</div>
<div class="content-fill">
<img {@|image-meta} />
</div>

NOTE: When using either content-fit or content-fill wrappers, it's important to remember that the containing element must have a width and height defined on it.

Focal Point

You can set the focal point for any image you upload – the point around which the system will always focus the image when using content-fill.

Original Dimensions

The following syntax can be used if you need to get hold of the original dimensions of the uploaded image:

{.main-image?}
<img src="{fullUrl}?format=750w" data-image-dimensions="{originalSize}" />
{.end}

For example, data-image-dimensions={500x300} is created for a 500px by 300px image. You can also break dimensions as follows:

{.main-image?}
<img src="{fullUrl}?format=750w" data-image-width="{originalSize|width}" data-image-height="{originalSize|height}" />
{.end}

Refreshing ImageLoader

The Squarespace ImageLoader automatically loads the appropriate version of any image depending on its context. However, this context might change due to a window resize or a tweak change and the image might require an update. The following is how you can do this using the imageLoader. Note that all functionality depends on the fact that data-image is available in the image tags which is automatically generated when using {@|image-meta}.

Example, on window resize:

Y.on( 'windowresize', function() { 
Y.all('img[data-src]' ).each(function(img) {
ImageLoader.load(img);
});
});