Browse by Topic

Referencing Assets in a Theme (Blueprint)

What We'll Cover


These instructions require knowledge of HTML/CSS. Don't feel comfortable adjusting your design or want to work with an expert? Visit our BigCommerce Partner Directory, or consider using the Community Jobs Board to post design and customization job requests and connect with third-party developers.

If you are a developer or making customizations to your store, you will probably be using asset files such as images, stylesheets, javascript, or other multimedia assets. The way you need to reference these in your code will differ slightly depending on where the files are stored.

The template assets only apply to our legacy Blueprint Themes and require familiarity with code. For Stencil theme references, see our Stencil developer documentation.

Assets can be stored in three locations, accessible through WebDAV:

  • Content: Used for PDFs and other non-design files.
  • Product_images/Uploaded_images: Corresponds to the Image Manager in the Control Panel.
  • Template: Uses the CDN (recommended)

WebDAV folder list with Contents, Template and Product_images highlighted.

Only the template folder uses the CDN. Therefore, we recommend storing all static assets in the template folder. For more information and examples, visit our Template Syntax on the Developer Portal.


Template Assets

We recommend all assets (with the exceptions listed above) be stored in the template folder or the appropriate subfolder. You can then reference these assets with the following format: %%ASSET_[path-to-your-asset]%%.

The %%ASSET_[path-to-your-asset] variable replaces the path of the template folder. So if you put an image in template/images, you would now reference the image with:

  • HTML: — <img src="%%ASSET_images/image.jpg%%" />
  • CSS: — background-image: url(%%ASSET_images/image.jpg%%);

Here's a breakdown of what's happening in this reference:

  • INPUT: %%ASSET_images/image.jpg%%
  • OUTPUT: http://cdn-host/templates/__custom/images/image.jpg?t=12345
  • CDN URL — the URL of the asset on the CDN
  • Timestamp ("cache buster") — the record of which version of the asset is being used; ensures your customers see the most recent version of your assets

Using %%ASSET_[path-to-your-asset]%% means you don't need to change the reference every time you make a change to the file, but can still utilize the benefits of the CDN. For more details and examples, see our Template Syntax documentation.


Other Assets

If you need to keep assets in folders outside of /template/, best practice is to use fully qualified URLs:

  • <img src="//" />
  • <img src="//" />

Images in the Image Manager will have a CDN URL. You can locate this URL by viewing it in its own window or tab.

  • <img src="//cdn-host/templates/__custom/Styles/myownstyle.css?t=12345" />

Was this article helpful?