Images are vital for eCommerce websites as they can show off products in their best light, which means you want to use high-quality images. But you also want the website to load quickly and have a good user experience.

BigCommerce uses a lot of best practices to ensure your images perform optimally. i.e. they look good and load fast.

This article explains some of those practices and gives tips on how to optimally add your images.

Some technical background

Before I go into all the ways you can add images to a BigCommerce store and how best to do it, I’d like to highlight some technical details that affect how optimal your images will be.

The Cloudflare CDN

BigCommerce uses Cloudflare to serve many of your images to users. You can tell when the CDN is in use as the image URL comes from a domain like Cloudflare offers several advantages for images:

A CDN stores images closer to the user (caches), which means they can be sent to them much faster.

For example. I’m in Adelaide Australia which is a long way from BigCommerce’s default servers in the USA. However, Cloudflare has a server in my city. If the images I want are already stored (cached) in my local server, they will load faster, and will avoid using data bandwidth across the world. It will also reduce the load on the BigCommerce servers.

Dynamic image conversion

Cloudflare dynamically converts images to the newer webp format (if it makes the file size smaller and the user’s browser supports it). The feature is called Cloudflare Polish.

This can be confusing as the URL still has the file extension of the original format like “.jpg”, but its content may actually be in webp format. You have to look at the file headers to see if it was converted to webp.

Cloudflare returning webp from a jpg URL

BigCommerce does not let you directly upload images in webp format as it has yet to be fully supported by browsers (not far off, though). It’s recommended to upload using JPG for photos and PNG for graphics.


Cloudflare uses HTTP2, meaning more images can be downloaded simultaneously. However, they will be competing for the network bandwidth, so it’s best to prioritise to ensure the important images get loaded quickly. More about that later.

Good caching policy

Cloudflare automatically adds good cache expiry headers so servers and browsers can hold on to a copy of the image for a long time, saving browsers from repeatedly downloading them from the original source. I think one year is plenty long enough.

Cache-control header set to one year

Responsive images

BigCommerce supports creating image URLs for different versions of an image in various sizes. This means a theme can request an image that is the perfect size for the place it will be shown, which means it will load faster and still look good. This is called a responsive image.

A bonus from this image resizing is that the image file size is compressed to be as small as possible. So you can upload the original high-resolution version, so that the resized versions are of good quality. BigCommerce recommends a size of 1280×1280 pixels, which is typically the largest a product image will be shown.

A good example would be a banner image that is the entire width of a device. Smaller mobile devices can download smaller images, while big desktops can download larger ones, and that’s good for everyone.

BigCommerce provides helpers to make it easier for theme developers to create responsive images. The logo, carousel, brand, category, and product images are typically responsive. You don’t want to have to create the responsive HTML manually:

BigCommerce theme code generating a responsive image.

Preparing your images

It’s good practice to get your images in order before you use them.

Image file names

Rename your image files so they concisely summarise what the image is about. You should stick to alphanumeric characters and dashes (-) in place of spaces. This results in nicer-looking image URLs and a slight boost for image SEO, and it helps you find your images. Some example file names:

  • nike-air-jordan-shoe-black-side-on.jpg
  • gold-heart-tag-pendant-necklace-being-worn.jpg
  • ford-mustang-convertible-red-2017-driving-though-hills.jpg

Image file compression and sizing

BigCommerce’s responsive images mean an image’s file is automatically compressed and generated in the sizes required. For them, you don’t need to pre-process the images. I’ll later indicate the scenarios where the image is responsive and compressed.

However, when adding images via the HTML editors, the image used is the one you provide. If you upload a gigantic image, the user must download a gigantic image!

In these cases, you should compress and size your images. One tool to do this is Swoosh which can both compress and resize an image. Give the image a width that matches the largest it will be shown. I suggest you add the images width to the new file name to make it easy to know what size it is. e.g.

  • ford-mustang-convertible-red-2017-driving-though-hills-w1280.jpg

I put a camera photo from my gallery into Swoosh, set it to be 1280px wide, and Swoosh compressed it down by 91% from 3.3MB to 301KB. That will undoubtedly load faster and still be good enough for a full-screen image.

Swoosh resizing and compressing an image

Where can you add images to BigCommerce?

There are lots of ways to add images to BigCommerce. Here I list most of them, with advice on how to optimally add them. Remember to rename your image files and use a tool like Swoosh to compress and resize them before uploading.

Logo, brand image, category image, blog thumbnail, home page carousel

These images are responsive and on the CDN and should be appropriately optimised and sized by the theme.

Product images

Product images are added to the site in a responsive way, so you don’t need to compress them first. You can reduce their size if they are way larger than 1280×1280 pixels. For quality, ensure they are at least 1280px wide, so they look good when zoomed in on. They are typically in JPG format, which is best for photos.

Product images are shown in many ways and sizes, all handled for you by the theme: thumbnails, main images, zoom image, category page images etc.

Please make sure to write a good description for each image. This description can help search rankings and help visually impaired people know what the image is about. Explain what is in the photo and give each image a different description. e.g.

  • The 2017 Red Convertible Ford Mustang driving through the Adelaide hills
  • The 2017 Red Convertible Ford Mustang parked by a beach
  • The 2017 Red Convertible Ford Mustang with the roof up
Adding image descriptions to the product images

HTML editors

Different parts of the admin interface include HTML editors to make it easier for you to format your content:

  • Product description
  • Category description
  • Web pages
  • Banners
  • Blog

When adding images to an HTML editor, you want to name, compress and resize them first. Size them based on the largest width they will be shown at.

Use jpg for photos (lossy but small) and png for non photos (lossless).

There are currently four HTML editors in use, each with their own functionality. What HTML editor you see where can vary from store to store.

HTML editor version 4 – 2020 tinymce 4.9.8

This is the latest editor and is the best at dealing with images. It may only be available for V3 product descriptions.

Here are some features of the new editor in relation to images:

  • Uses the CDN and its benefits
  • You can drag and drop images into the editor to add them.
  • You can specify width and height, but this does not resize the underlying image. If you size them here, ensure the image’s actual size is the same.
  • Because they have a width and height (to calculate their aspect ratio), they will not cause layout shifts.
  • Edit the image and add an image description for accessibility and image SEO (alt attribute)
  • You can’t upload webp, but CloudFlare converts to webp if it is smaller and the browser supports it.
Product description editor and adding/editing an image
Adding a product image description

HTML editor version 3 – tinymce

This is similar to the version 4, however you add an image via the “Insert” menu, you can’t drag and drop images in, and you want to fill in the “Alternate description”

HTML editor version 2 – 2013 tinymce

This one is showing its age, and has a few issues. It defaults to a poor title and alt (image description). I suggest blanking out the title and creating a good alt.

However it does size the images and convert the URLs to the CDN for speed.

I noticed that sometimes the image editor did not work after the upload. However, the image was placed in the gallery, so a cancel, new insert and selecting it from the gallery would fix things.

HTML editor version 1 – Redactor 9.1.9

I believe all blog posts use this clunky editor.

Unfortunately, it does not use the CDN or size the images. And I’ve seen at times that the image URLs are for the temporary domain, which means they are blocking Google and the other search engines from indexing them.

I think you should edit your content in the best BigCommerce editor you have access to, save it (to generate the CDN URLs) then copy its HTML into this editor. That way, the images will be on the CDN and will be sized.


Unfortunately, widgets are a bit of a black box, making fixing their issues from the outside hard. And they have issues. I am not a fan of the current widgets.

In most cases, the widget does not process your images, so rename, resize and compress them before uploading. Work out the maximum width they can be displayed at, and go with that.

I find the widgets are mostly terrible for speed and stability. I’d personally hand-code these features into the theme or use the HTML widget, so I have complete control over how things work.

Image widget

Images can be added in several ways. If you upload or grab it from the existing images, it will be placed on the CDN. If you specify a URL, then it will stick with that URL.

By default, the widget does not size the image. This means it will cause a layout shift as the image loads. And that’s bad for your Core Web Vitals.

This video shows an example of the shift (see how the text is pushed down) as well as how slow things can be if you do not optimise your images.

One solution could be to change the image dimensions to “Custom” and specify a specific height (which should match the actual height of the image). Unfortunately this means it is no longer responsive to the pages width.

It would be nice if the widget provided a way to specify the original dimensions or its aspect ratio. Then the image could be responsive while avoiding a layout shift.

Remember to go into the SEO section and add some alt text explaining what is in the image.

Strangely it includes the image in an img tag and in CSS. Not sure why, but there is no harm.

Hero banner widget

This one provides no way of specifying the image’s dimensions, so it is guaranteed to cause a layout shift. I’ve seen this widget be the leading cause of failed CLS on several stores.

The image is not initially present in the source but is dynamically added by JavaScript in CSS. This makes it a really slow loader (it has to wait for the JavaScript to load and execute before it is known about, and then CSS images are a low load priority). This will likely mean the page will fail LCP, as the hero image is often the main content on a page.

It is also unlikely to be indexed by search engines as it is not an img tag and requires JavaScript for the search engines to see it.

Please do not use it.

Carousel widget

The same issues as the banner image. Slow and shifty. Please do not use.

Product widget

This one uses JavaScript to load all the content of the widget and its CSS.

It’s complicated, with up to two sequential resource requests before it can create the widget, which then triggers the loading of the image.

Guess what, slow and shifty, do not use.

Product set widget

This one has the same code structure as the product widget, so it is also slow and shifty.

It actually uses img tags with alt text. Which means they could potentially show up in image search results.

There is an attempt to make them responsive so that an appropriately sized image is used, but they forgot to add the sizes attribute. This means it assumes all images need to be the full width of the device, so in most cases it will load an image that is larger than required.

For good measure, they set the images to lazy load. Probably insignificant after all the previous delays in loading them.

Good try, but another fail for user experience and the Core Web Vitals. don’t use.

Bulk image importing

BigCommerce have a few resources on bulk product image importing.

The general idea is to import the products via a CSV file that includes the URLs of their images.

One good way to get the images themselves imported is to use WebDAV…

WebDAV for images

WebDAV lets you upload files to your website and access them from your domain. It can be an excellent way to bulk upload and use images. Images here are not by default optimised, so like always, upload appropriately named, sized and compressed versions.

In Stencil/handlebars, you can reference them via the CDN using a command like this (assuming the image is in content/images):

<img src="{{cdn 'webdav:images/my-image.jpg'}}" alt="My image" /> 

If you are on cdn11 and your store hash is my-store-hash, the resulting HTML would look like this:

<img src="" alt="My image" /> 

When importing products you can reference the images stored in WebDAV. This is a great way to bulk add products with images. These images should also be served via the CDN (not checked).

You can also reference the webDAV images in the html editor but in this case they are not served by the CDN, unless you work out their CDN URL knowing your CDN number and store hash.

For BigCommerce and theme developers

What I think BigCommerce should do

Here are some quick pointers on what I think BigCommerce should do to improve how images are handled:

  • Update the blog HTML editor
  • Speed up their HTML response time
  • Support image early hints if/where possible (non-responsive or full width images)
  • Support AVIF conversions (a Cloudflare thing)

What I think theme developers should do

Here are some quick pointers on what I think theme developers should do to improve how they handle images. BigCommerce should also update Cornerstone with these changes:

  • Improve how responsive images are built (e.g. the Cornerstone responsive-img component)
  • Don’t lazy load prominent images
  • Use fetchpriority high for prominent images to improve LCP
  • Use fetchpriority low on hidden images like secondary slides and the product zoom image
  • Use img decoding=”async” on off screen images which moves decoding off the main thread
  • Avoid Layout Shifts due to images by adding height/width/aspect-ratio.
  • Stop using JavaSscript based lazyloading and go native (92% supported)
  • preload prominent images
  • Don’t add important images via CSS, use the img tag

And some more articles from me: