Skip to main content
You need to be on Spree 5.0.1 or higher to use these helpers. If you’re on 5.0.0 please run bundle update spree to update your Spree version.
Spree comes with a handful of helper methods to make it easier to work with images and assets.

​
Helpers

Spree provides several helper methods for working with images in your storefront. These methods are defined in Spree::ImagesHelper and are available in your views.

​
spree_image_tag

This helper generates an image with specified width and height. It automatically scales the width and height by 2x to look great on retina screens. The output will be always in WebP format for great performance. 
<%= spree_image_tag(
  product.image, 
  width: 100, 
  height: 100, 
  loading: :lazy,
  class: 'w-full group-hover:opacity-0 transition-opacity duration-500 z-10 relative h-full bg-background product-card !max-h-full object-cover object-center', 
  title: 'Product Image', 
  alt: 'Product Image') 
%>
this will generate HTML image element with the following attributes: 
<img 
  width="100" 
  height="100" 
  loading="lazy" 
  class="w-full group-hover:opacity-0 transition-opacity duration-500 z-10 relative h-full bg-background product-card !max-h-full object-cover object-center" 
  src="https://yourspreestore.com/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MjEwNywicHVyIjoiYmxvYl9pZCJ9fQ==--61de214902195c6ad6cf382ef777b1ab737c9eea/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9LCJyZXNpemVfdG9fZmlsbCI6WzYwMCw2MDBdfSwicHVyIjoidmFyaWF0aW9uIn19--34a1e32c85a20d458ee056019da3ed415a92106e/Photo-8.png">
If both width and height are not provided, the helper will keep the image original aspect ratio. If necessary, will crop the image in the larger dimension. If only one of the width or height is provided, the helper will be resized only by the provided dimension. You can pass additional options same as with standard Rails image_tag helper. The first argument needs to be a either ActiveStorage attachment (eg. taxon.image) or a Spree::Asset object. Under the hood this helper uses spree_image_url to generate the image URL.

​
spree_image_url

This helper generates a URL for a Spree image. It automatically scales the width and height by 2x to look great on retina screens. The output will be always in WebP format for great performance. 
<%= spree_image_url(product.image, width: 100, height: 100) %>
This will generate a URL for the image with the specified width and height. 
https://yourspreestore.com/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MjEwNywicHVyIjoiYmxvYl9pZCJ9fQ==--61de214902195c6ad6cf382ef777b1ab737c9eea/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9LCJyZXNpemVfdG9fZmlsbCI6WzYwMCw2MDBdfSwicHVyIjoidmFyaWF0aW9uIn19--34a1e32c85a20d458ee056019da3ed415a92106e/Photo-8.png
If both width and height are not provided, the helper will keep the image original aspect ratio. If necessary, will crop the image in the larger dimension.
URLs generated by this helper are always static and can be easily cached by CDNs. You shouldn’t use this helper method for private assets!

​
spree_asset_aspect_ratio

This helper returns the aspect ratio of an image or video. It can be used in CSS to maintain the correct aspect ratio of an image. 
<%= spree_asset_aspect_ratio(product.image) %>
This will return the aspect ratio of the image as a float. 
1.5
It can auto-detect if the asset is a portrait or landscape image and return the correct aspect ratio. If both width and height are equal, it will return 1.