Skip to content

docs: Add lossy parameter documentation for Stencil image helpers #1064

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

docs: Add lossy parameter documentation for Stencil image helpers #1064

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8af1790
Initial plan
Copilot Aug 24, 2025
884bbe3
Initial plan: Update Stencil image helpers documentation for lossy pa…
Copilot Aug 24, 2025
9781b82
Update Stencil image helpers documentation with lossy parameter
Copilot Aug 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 57 additions & 6 deletions docs/storefront/stencil/themes/context/handlebars-reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -810,10 +810,16 @@ Returns language translation keys as a JSON string.
- [See it in GitHub](https://github.com/bigcommerce/paper-handlebars/blob/master/helpers/langJson.js)
- [See it in Cornerstone](https://github.com/bigcommerce/cornerstone/search?l=HTML&q=langJson)

## Image optimization

All Stencil image helpers support an optional `lossy` parameter that enables image optimization for better performance. When `lossy=true` is specified, the helper applies lossy compression that results in smaller file sizes and enables automatic WebP conversion for supported browsers. This optimization can significantly improve page load times and reduce bandwidth usage while maintaining acceptable image quality.

The `lossy` parameter is available for all image helpers including `getContentImage`, `getContentImageSrcset`, `getImageManagerImage`, `getImageManagerImageSrcset`, and `getImageSrcset`.

### getContentImage

```handlebars showLineNumbers
{{getContentImage path width height}}
{{getContentImage path width height lossy}}
```

Returns a URL for an image uploaded to `/dav/content/`. To learn more about uploading files to your store's server, see [WebDAV](https://support.bigcommerce.com/s/article/File-Access-WebDAV).
Expand All @@ -823,6 +829,7 @@ Returns a URL for an image uploaded to `/dav/content/`. To learn more about uplo
- `path` (String): Image path relative to `/dav/content/`.
- `width` (Integer): Width in pixels.
- `height` (Integer): Height in pixels.
- `lossy` (Boolean): Optional. When `true`, enables lossy compression for smaller file sizes and automatic WebP conversion. Defaults to `false`.

#### Example

Expand All @@ -840,21 +847,29 @@ Returns a URL for an image uploaded to `/dav/content/`. To learn more about uplo

{{getContentImage "asset.jpg" width=123}}
<!-- => https://cdn.bcapp/3dsf74g/images/stencil/123w/content/folder/asset.jpg -->

<!-- With lossy compression for optimized images -->
{{getContentImage "asset.jpg" width=123 height=321 lossy=true}}
<!-- => https://cdn.bcapp/3dsf74g/images/stencil/123x321/content/asset.jpg?compression=lossy -->

{{getContentImage "asset.jpg" width=123 lossy=true}}
<!-- => https://cdn.bcapp/3dsf74g/images/stencil/123w/content/folder/asset.jpg?compression=lossy -->
```

- [See it in GitHub](https://github.com/bigcommerce/paper-handlebars/blob/master/helpers/getContentImage.js)

### getContentImageSrcset

```handlebars showLineNumbers
{{getContentImageSrcset path}}
{{getContentImageSrcset path lossy}}
```

Returns a `srcset` for an image uploaded to `/dav/content/`.

#### Parameters

- `path` (String): Image path relative to `/dav/content/`.
- `lossy` (Boolean): Optional. When `true`, enables lossy compression for smaller file sizes and automatic WebP conversion. Defaults to `false`.

#### Example

Expand All @@ -864,14 +879,18 @@ Returns a `srcset` for an image uploaded to `/dav/content/`.

{{getContentImageSrcset "folder/asset.jpg" width=123}}
<!-- => https://cdn.bcapp/3dsf74g/images/stencil/80w/content/folder/asset.jpg 80w, https://cdn.bcapp/3dsf74g/images/stencil/160w/content/folder/asset.jpg 160w, https://cdn.bcapp/3dsf74g/images/stencil/320w/content/folder/asset.jpg 320w, https://cdn.bcapp/3dsf74g/images/stencil/640w/content/folder/asset.jpg 640w, https://cdn.bcapp/3dsf74g/images/stencil/960w/content/folder/asset.jpg 960w, https://cdn.bcapp/3dsf74g/images/stencil/1280w/content/folder/asset.jpg 1280w, https://cdn.bcapp/3dsf74g/images/stencil/1920w/content/folder/asset.jpg 1920w, https://cdn.bcapp/3dsf74g/images/stencil/2560w/content/folder/asset.jpg 2560w -->

<!-- With lossy compression for optimized images -->
{{getContentImageSrcset "asset.jpg" lossy=true}}
<!-- => https://cdn.bcapp/3dsf74g/images/stencil/80w/content/asset.jpg?compression=lossy 80w, https://cdn.bcapp/3dsf74g/images/stencil/160w/content/asset.jpg?compression=lossy 160w, https://cdn.bcapp/3dsf74g/images/stencil/320w/content/asset.jpg?compression=lossy 320w, https://cdn.bcapp/3dsf74g/images/stencil/640w/content/asset.jpg?compression=lossy 640w, https://cdn.bcapp/3dsf74g/images/stencil/960w/content/asset.jpg?compression=lossy 960w, https://cdn.bcapp/3dsf74g/images/stencil/1280w/content/asset.jpg?compression=lossy 1280w, https://cdn.bcapp/3dsf74g/images/stencil/1920w/content/asset.jpg?compression=lossy 1920w, https://cdn.bcapp/3dsf74g/images/stencil/2560w/content/asset.jpg?compression=lossy 2560w -->
```

- [See it in GitHub](https://github.com/bigcommerce/paper-handlebars/blob/master/helpers/getContentImageSrcset.js)

### getImage

```handlebars showLineNumbers
{{getImage stencilImage size}}
{{getImage stencilImage size lossy}}
```

Returns `<img>` tag `src` value for images of a specified size. Values for the size parameter are defined in the `settings` array in [`config.json`](https://github.com/bigcommerce/cornerstone/blob/master/config.json).
Expand All @@ -881,11 +900,15 @@ Returns `<img>` tag `src` value for images of a specified size. Values for the s
- `stencilImage` (String): A Stencil image.
- `size` (String): A key in the `theme_settings` object.
- `defaultImage` (String): Optional default image URL to use if the `stencilImage` is undefined.
- `lossy` (Boolean): Optional. When `true`, enables lossy compression for smaller file sizes and automatic WebP conversion. Defaults to `false`.

#### Example

```handlebars showLineNumbers
{{getImage image "logo"}}

<!-- With lossy compression for optimized images -->
{{getImage image "logo" lossy=true}}
```

- [See it in GitHub](https://github.com/bigcommerce/paper-handlebars/blob/master/helpers/getImage.js)
Expand All @@ -894,7 +917,7 @@ Returns `<img>` tag `src` value for images of a specified size. Values for the s
### getImageManagerImage

```handlebars showLineNumbers
{{getImageManagerImage path width height}}
{{getImageManagerImage path width height lossy}}
```

Returns an [Image Manager](https://support.bigcommerce.com/s/article/Using-the-Image-Manager) image URL for an image uploaded to `/dav/product_images/uploaded_images`. To learn more about uploading files to your store's server, see [WebDAV](https://support.bigcommerce.com/s/article/File-Access-WebDAV).
Expand All @@ -904,6 +927,7 @@ Returns an [Image Manager](https://support.bigcommerce.com/s/article/Using-the-I
- `path` (String): Image path relative to `/dav/product_images/uploaded_images`.
- `width` (Integer): Width in pixels.
- `height` (Integer): Height in pixels.
- `lossy` (Boolean): Optional. When `true`, enables lossy compression for smaller file sizes and automatic WebP conversion. Defaults to `false`.

#### Example

Expand All @@ -922,21 +946,29 @@ Returns an [Image Manager](https://support.bigcommerce.com/s/article/Using-the-I

{{getImageManagerImage "folder/asset.jpg" width=123 height=321}}
<!-- => https://cdn.bcapp/3dsf74g/images/stencil/123x321/image-manager/folder/asset.jpg -->

<!-- With lossy compression for optimized images -->
{{getImageManagerImage "asset.jpg" width=123 lossy=true}}
<!-- => https://cdn.bcapp/3dsf74g/images/stencil/123w/image-manager/asset.jpg?compression=lossy -->

{{getImageManagerImage "folder/asset.jpg" width=123 height=321 lossy=true}}
<!-- => https://cdn.bcapp/3dsf74g/images/stencil/123x321/image-manager/folder/asset.jpg?compression=lossy -->
```

- [See it in GitHub](https://github.com/bigcommerce/paper-handlebars/blob/master/helpers/getImageManagerImage.js)

### getImageManagerImageSrcset

```handlebars showLineNumbers
{{getImageManagerImageSrcset path}}
{{getImageManagerImageSrcset path lossy}}
```

Returns an [Image Manager](https://support.bigcommerce.com/s/article/Using-the-Image-Manager) image `srcset` for an image uploaded to `/dav/product_images/uploaded_images`. To return an image with a specified image width and height size, we recommend using the `getImageManagerImage` helper.

#### Parameters

- `path` (String): Image path relative to `/dav/product_images/uploaded_images`.
- `lossy` (Boolean): Optional. When `true`, enables lossy compression for smaller file sizes and automatic WebP conversion. Defaults to `false`.

#### Example

Expand All @@ -948,14 +980,19 @@ https://cdn.bcapp/3dsf74g/images/stencil/80w/image-manager/asset.jpg 80w, https:
{{getImageManagerImageSrcset "folder/asset.jpg"}}
<!-- =>
https://cdn.bcapp/3dsf74g/images/stencil/80w/image-manager/folder/asset.jpg 80w, https://cdn.bcapp/3dsf74g/images/stencil/160w/image-manager/folder/asset.jpg 160w, https://cdn.bcapp/3dsf74g/images/stencil/320w/image-manager/folder/asset.jpg 320w, https://cdn.bcapp/3dsf74g/images/stencil/640w/image-manager/folder/asset.jpg 640w, https://cdn.bcapp/3dsf74g/images/stencil/960w/image-manager/folder/asset.jpg 960w, https://cdn.bcapp/3dsf74g/images/stencil/1280w/image-manager/folder/asset.jpg 1280w, https://cdn.bcapp/3dsf74g/images/stencil/1920w/image-manager/folder/asset.jpg 1920w, https://cdn.bcapp/3dsf74g/images/stencil/2560w/image-manager/folder/asset.jpg 2560w -->

<!-- With lossy compression for optimized images -->
{{getImageManagerImageSrcset "asset.jpg" lossy=true}}
<!-- =>
https://cdn.bcapp/3dsf74g/images/stencil/80w/image-manager/asset.jpg?compression=lossy 80w, https://cdn.bcapp/3dsf74g/images/stencil/160w/image-manager/asset.jpg?compression=lossy 160w, https://cdn.bcapp/3dsf74g/images/stencil/320w/image-manager/asset.jpg?compression=lossy 320w, https://cdn.bcapp/3dsf74g/images/stencil/640w/image-manager/asset.jpg?compression=lossy 640w, https://cdn.bcapp/3dsf74g/images/stencil/960w/image-manager/asset.jpg?compression=lossy 960w, https://cdn.bcapp/3dsf74g/images/stencil/1280w/image-manager/asset.jpg?compression=lossy 1280w, https://cdn.bcapp/3dsf74g/images/stencil/1920w/image-manager/asset.jpg?compression=lossy 1920w, https://cdn.bcapp/3dsf74g/images/stencil/2560w/image-manager/asset.jpg?compression=lossy 2560w -->
```

- [See it in GitHub](https://github.com/bigcommerce/paper-handlebars/blob/master/helpers/getImageManagerImageSrcset.js).

### getImageSrcset

```handlebars showLineNumbers
{{getImageSrcset stencilImage size}}
{{getImageSrcset stencilImage size lossy}}
```

The `getImageSrcset` helper is a replacement for [`getImage`](#getImage) which allows you to generate either a single image URL (for an `<img>` `src`) or a list of image sizes for `srcset`. Using the [srcset](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-srcset) attribute, you can specify a list of image sizes for the browser to choose from based on the expected size of the image on the page, the device's pixel density, and other factors.
Expand All @@ -965,6 +1002,7 @@ The `getImageSrcset` helper is a replacement for [`getImage`](#getImage) which a
- `stencilImage` (String): A Stencil image.
- `size` (String): A key in the `theme_settings` object.
- `defaultImage` (String): Optional default image URL to use if the `stencilImage` is undefined.
- `lossy` (Boolean): Optional. When `true`, enables lossy compression for smaller file sizes and automatic WebP conversion. Defaults to `false`.

You can specify what sizes you want as named arguments on the helper.

Expand All @@ -977,6 +1015,10 @@ By specifying `use_default_sizes=true` on the helper, a `srcset` string will be
```handlebars showLineNumbers
{{getImageSrcset image use_default_sizes=true}}
{{getImageSrcset image "https://place-hold.it/500x300" use_default_sizes=true}}

<!-- With lossy compression for optimized images -->
{{getImageSrcset image use_default_sizes=true lossy=true}}
{{getImageSrcset image "https://place-hold.it/500x300" use_default_sizes=true lossy=true}}
```

Default sizes:
Expand All @@ -998,6 +1040,9 @@ Default sizes:
{{getImageSrcset image 1x=theme_settings.zoom_size}}
{{getImageSrcset image 1x="1280x800"}}
{{getImageSrcset image 1x="1280w"}}

<!-- With lossy compression -->
{{getImageSrcset image 1x="1280w" lossy=true}}
```

By specifying a single size as `1x`, you can choose any image resolution. You can reference a value from the `theme_settings` object (similar to `getImage`), or you can specify your own size inline. `getImageSrcset` does not require `theme_settings` keys to be wrapped in quotes; they should be referenced directly.
Expand All @@ -1008,6 +1053,9 @@ By specifying a single size as `1x`, you can choose any image resolution. You ca
{{getImageSrcset image 1x="1280w" 2x="2560w"}}
{{getImageSrcset image 1x="800w" 1.5x="1200w" 2x="1600w"}}
{{getImageSrcset image 1x="640x640" 2x="1280x1280"}}

<!-- With lossy compression -->
{{getImageSrcset image 1x="1280w" 2x="2560w" lossy=true}}
```

By specifying several sizes using the pixel density descriptor, you can generate a `srcset` of different image resolutions for different pixel density screens as described in [Resolution switching: Same size, different resolutions](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images#Resolution_switching_Same_size_different_resolutions). For example, you can specify a `2x` image for Retina screens, and a `1x` image for normal screens.
Expand All @@ -1026,6 +1074,9 @@ As above, you can reference `theme_settings` keys or specify your own size inlin

<!-- =>
<img src="https://cdn11.bigcommerce.com/s-abc123/images/stencil/640x640/products/86/286/ablebrewingsystem4_1024x1024__07155.1456436672.jpg?c=2" srcset="https://cdn11.bigcommerce.com/s-abc123/images/stencil/100w/products/86/286/ablebrewingsystem4_1024x1024__07155.1456436672.jpg?c=2 100w, https://cdn11.bigcommerce.com/s-abc123/images/stencil/200w/products/86/286/ablebrewingsystem4_1024x1024__07155.1456436672.jpg?c=2 200w,https://cdn11.bigcommerce.com/s-abc123/images/stencil/300w/products/86/286/ablebrewingsystem4_1024x1024__07155.1456436672.jpg?c=2 300w" /> -->

<!-- With lossy compression for optimized images -->
<img src="{{getImage image 'default'}}" srcset="{{getImageSrcset image 100w='100w' 200w='200w' 300w='300w' lossy=true}}" />
```

By specifying several sizes using the inherent width descriptor, you can generate a `srcset` of different image resolutions based on width, which can in turn be selected by the browser based on the expected size of the image when the page is painted. It is recommended to use this together with a `sizes` attribute on the `<img>` element as described in [Resolution switching: Different sizes](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images#Resolution_switching_Different_sizes). In Cornerstone, this is handled automatically via JavaScript.
Expand Down
2 changes: 1 addition & 1 deletion package-lock.json
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.