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 creates multiple copies of the image with different sizes. Our image loader will then help render images at the proper size, even on retina displays.

The ImageLoader can also be used to fit or fill an image inside 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:

<!-- Add the imageLoader JSON-T formatter to an img tag -->
<img {@|image-meta} />

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

<!-- img tag is rendered with additional attributes -->
<img class="thumb-image loaded" data-src="http://static1.squarespace.com/static/577e80de20099e0c9b023125/t/577e823fd482e949405e881d/1467908686952/" data-image="http://static1.squarespace.com/static/577e80de20099e0c9b023125/t/577e823fd482e949405e881d/1467908686952/" data-image-dimensions="1500x1000" data-image-focal-point="0.5,0.5" data-load="false" data-image-id="577e823fd482e949405e881d" data-type="image" alt="This is an image caption within a blog post." src="https://static1.squarespace.com/static/577e80de20099e0c9b023125/t/577e823fd482e949405e881d/1467908686952/?format=750w" data-image-resolution="750w">

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.

Running and Refreshing ImageLoader

In order to leverage the imageLoader built into Squarespace, we've got to initialize the script. Basically, we rely on the data-src attribute being present as a hook which is automatically generated for us when {@|image-meta} is used.

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 Style Editor change and the image might require an update. The following example script will run imageLoader on load and resize.

// Load all images via Squarespace's Responsive ImageLoader
function loadAllImages() {
  var images = document.querySelectorAll('img[data-src]' );
  for (var i = 0; i < images.length; i++) {
    ImageLoader.load(images[i], {load: true});
  }
}

// The event subscription that loads images when the page is ready
document.addEventListener('DOMContentLoaded', loadAllImages);

// The event subscription that reloads images on resize
window.addEventListener('resize', loadAllImages);

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:

2500w, 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.

{.section mainImage}
    <img {@|image-meta} />
{.or}
    <img src="/assets/default-image.jpg" />
{.end}

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.

<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 wrapper classes, the containing element must have a width and height defined.

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}