Overview

🚧 Due to a bug on Apple's Core Image Framework, images with a single color palette (e.g., red) might not be displayed on macOS + Safari. To fix that, we recommend using format="png".

The ResponsiveImage component is designed to:

Load appropriately sized images based on device screen width by providing the srcSet property for you.
Automatically load appropriate quality and image format (e.g. webp when possible).
Polyfill lazy loading support when needed.

These optimizations only work for images that are uploaded using Shogun Frontend to our CDN. For external images, there's no benefit to this component other than lazy loading.

Import

The ResponsiveImage component can be imported directly from the frontend-ui package, which is pre-installed in your Shogun Frontend store.

import ResponsiveImage from 'frontend-ui/ResponsiveImage'

Usage

import React from 'react'
import ResponsiveImage from 'frontend-ui/ResponsiveImage' 

const SomeComponent = ({ someImage }) => {
  // assuming `someImage.src` = https://f.shgcdn.com/cbc7d039-b532-42d4-979a-2c8180befadd/
  if (!someImage || !someImage.src) return
  
  // Using the sizes prop, we're telling the browser that
  // for smaller screens, this image takes about 80% of the screen width, 
  // and for bigger screens it's just 40%.
  // The `sizes` prop helps the browser load an appropriately sized image.
  // Those values don't need to be exact.
  return (
    <ResponsiveImage
      src={someImage.src}
      width={someImage.width}
      height={someImage.height}
      sizes="(max-width: 767px) 80vw, 40vw"
      alt="A black t-shirt with a black Shogun logo on it. The t-shirt is on a red surface."
    />
  )
}

export default SomeComponent

Result:

Props

ResponsiveImage accepts the following props in addition to any attribute that img HTML element accepts:

name	type	default value	description
`src`	`string`		The image url source. This is required.
`alt`	`string`		Defines an alternative text description of the image. Recommended.
`loading`	`eager` \| `lazy` \| `preload`	`lazy`	Determine whether the image should be lazy loaded or immediately loaded on the page load. Use `loading="preload"` with caution. This optimization should only be used for the main hero background image that is the Largest Contentful Paint (LCP) on a page. You should measure the impact of this strategy as it can cause a negative impact.
`priority`	`boolean`	`false`	⚠️ Deprecated, use `loading="preload"` instead. If true, it adds an image preload link to the head. Lazy loading is automatically disabled for images using priority.
`sizes`	`string`		Indicate a set of source sizes. See example above. sizes overview on MDN.
`srcSet`	`string`		Auto-generated to adapt the image to different screen sizes. It will be overwritten if using a custom srcSet. Do not use `srcset`, use `srcSet` (note the uppercased S).
`quality`	`lightest` \| `lighter` \| `normal` \| `better` \| `best` \| `smart`	`smart`	Sets the quality of the image.
`format`	`jpg` \| `png` \| `webp` \| `auto`	`auto`	Sets the format of the image.
`crop`	`string` (example: `100x200`)		Crops the image to a given dimension.
`width`	`string` (example: `2560`)		Sets the width of the image. Recommended to avoid layout shifting.
`height`	`string` (example: `1440`)		Sets the height of the image. Recommended to avoid layout shifting.

FAQ

Q: Are images optimized on upload?
A: Images are not optimized on upload. The user uploads a raw image, and it is saved in the same format in storage. When storefront users request an optimized image, Cloudinary, the image service we are using, loads that image on the fly, transforms, optimizes, and caches it. When the user requests the same image again, it will be served from the cache, which will be faster than pulling it from storage and transforming it.

Q: How do we handle images? How should we advise users to choose image sizes?
A: The browser determines the served image size. Shogun's ResponsiveImage tells the browsers which sizes to choose from (users can change our default option), and the sizes attribute tells the browser how much space the image should occupy on the screen (e.g., 50% of device, default is 100%). The browser will select the most optimal size based on these two inputs.

Q: At what point is image size affecting the page speed?
A: There is not a single point; it is linear. Fewer, smaller images will always be better for performance. Page speed can also be affected by loading too many resources or images at the same time. It is important to leverage lazyLoading when possible to reduce the strain on internet bandwidth. Also note, in 5% of cases, the image could load slowly because it isn’t stored properly in Cloudinary's cache. This will improve in the future. You can test to see if this is happening by visiting the same page with browser cached turned off to see if the images continue to load slowly-- if so, this is not an issue.

ResponsiveBackgroundImage

Video

getResponsiveImageSrc

Frontend Lazy

Best Practices