Blog Ecommerce March 6, 2026 6 min read

Squarespace Product Image Placeholder Strategy for Shops

Handle missing Squarespace product images in commerce blocks using Developer Mode custom code and onerror fallback URLs sized for product grids.

Squarespace product imageSquarespace commerceImage fallbackEcommerce placeholderSquarespace Developer Mode

Squarespace Product Image Placeholder Strategy for Shops

Squarespace commerce blocks render product grids where every item is expected to have at least one product image. When a product is created without images — common during catalog setup or bulk import from another platform — the product grid collapses that item's image slot, breaking the visual alignment of the entire grid row.

Squarespace limits direct template access outside of Developer Mode. The most reliable cross-plan solution is a custom code block with a JavaScript snippet that detects broken or absent product images and replaces them with a generated fallback URL.

Squarespace image behavior

How Squarespace handles products without images

In Squarespace Commerce, a product with no images renders its grid item with a gray box or a missing-image icon depending on the template. Some templates completely omit the image element, which collapses the card height. Either way, the product card looks unfinished in the store.

Squarespace does not expose a template-level fallback image configuration for product images outside of Developer Mode. Standard plans are limited to injecting JavaScript or CSS through Settings > Advanced > Code Injection.

Developer Mode (available on Business plans and above) gives access to `.item` template files where you can add conditional logic to output a fallback src directly in the markup.

Code injection

JavaScript fallback for all Squarespace plans

The code injection approach works on every Squarespace plan. Add the script to Settings > Advanced > Code Injection > Footer. It queries product grid images and attaches onerror handlers that substitute a generated fallback URL when the image fails to load.

Target Squarespace product images by their data attributes or class names. Squarespace uses the `sqspc-product-image` class and `data-collection-item-id` attributes on product cards. Targeting by these stable identifiers is safer than class names that vary per template.

Implementation text

<script>
(function () {
  function applyProductFallbacks() {
    var images = document.querySelectorAll(
      '.ProductItem-gallery-slides img, .products-item-image img'
    );
    images.forEach(function (img) {
      if (!img.complete || img.naturalWidth === 0) {
        img.onerror = function () {
          this.src = 'https://fallback.pics/api/v1/600x600?text=Product+Image';
          this.onerror = null;
        };
        if (img.complete && img.naturalWidth === 0) {
          img.src = 'https://fallback.pics/api/v1/600x600?text=Product+Image';
        }
      }
    });
  }

  if (document.readyState === 'loading') {
    document.addEventListener('DOMContentLoaded', applyProductFallbacks);
  } else {
    applyProductFallbacks();
  }
})();
</script>

Developer Mode

Template-level fallback in Developer Mode

In Developer Mode, Squarespace templates use JSON-T (JSONT) as their templating language. Product data is available in the template context, and image collections are arrays of image objects. An empty products list or a product with an empty `items` array requires a conditional check.

JSONT syntax uses `{.if}` blocks for conditionals. Check whether the image collection is populated before rendering the image element, and output a fallback `<img>` in the else branch.

Implementation text

{# JSONT template fragment for a product image block #}
{.section product}
  {.repeated section items}
    {.section assetUrl}
      <img src="{@}" alt="{title}" width="600" height="600" />
    {.or}
      <img
        src="https://fallback.pics/api/v1/600x600?text={title|htmltag}"
        alt="{title}"
        width="600"
        height="600"
      />
    {.end}
  {.end}
{.end}

Square images

Use square fallbacks for product grid consistency

Squarespace product grids expect square or consistent-aspect-ratio images. A 1:1 fallback (600×600) matches the most common product grid layout. If your store uses a 4:3 or 3:2 layout, adjust the fallback dimensions accordingly.

The square placeholder route is a shortcut for 1:1 images: `https://fallback.pics/api/v1/square/600?text=Product`. It generates a properly sized square without needing to specify both width and height.

Implementation text

// Square product placeholder — matches 1:1 Squarespace product grids
https://fallback.pics/api/v1/square/600?text=Product+Image

// Product thumbnail for cart and order confirmation pages
https://fallback.pics/api/v1/square/200?text=Item

// Larger 4:3 fallback for wide-format product pages
https://fallback.pics/api/v1/800x600?text=Product+Photo

Catalog import

Protect the store during catalog imports

Squarespace Commerce supports CSV product imports. When importing a large catalog, product images are added separately after the initial CSV import completes. During this window, products are live but image slots are empty.

Having the JavaScript fallback already in place means the store is protected from the moment products appear. Customers see a labeled placeholder rather than an empty card, and product grids maintain their visual alignment throughout the import process.

Resources

What to standardize before shipping

Squarespace product grids collapse or show broken icons when products have no images — inject a fallback script via Code Injection for all plans.
Use a 1:1 (square) fallback URL to match standard Squarespace product grid layouts.
Attach onerror handlers to product images and set onerror = null immediately after to prevent infinite reload loops.
Developer Mode enables template-level JSONT conditionals for cleaner fallback logic without JavaScript.
Pre-deploy the fallback script before starting catalog imports so every gap in the import process is covered.

Production fallback layer