Image

On the frontend, the Image component shows a responsive optimized image with progressive loading (lazy load).

On the Admin, it allows to upload a new image, opening a modal that allows you to set the alternate text (ALT) and SEO-friendly name (for the image URL).

In order to boost performance and SEO, upon upload, React Bricks will:

• Create responsive optimized images
• Create the srcSet to be used on the frontend for the optimal image selection
• Create a light blurred placeholder for the progressive loading
• Save them on a global CDN
• Enforce the SEO-friendly name via proper rewrite rules

📌

For usage with Next /App Router, please read the React Server Components Guide.

Properties

Here's the Typescript interface for the props of the Image component:

interface ImageProps {
  propName: string
  alt: string
  maxWidth?: number
  noLazyLoad?: boolean
  aspectRatio?: number
  containerClassName?: string // Deprecated from 3.3.0
  containerStyle?: object // Deprecated from 3.3.0
  imageClassName?: string
  imageStyle?: object
  noWrapper?: boolean // Deprecated from 3.3.0
  quality?: number // New in v4.3
  sizes?: string
  loading?: 'lazy' | 'eager'
  renderWrapper?: RenderWrapper
  useNativeLazyLoading?: boolean
  useWebP?: boolean
  metaFieldName?: 'image'
  customFieldName?: string
  placeholder?: (props: PlaceholderProps) => string
  readonly?: boolean // New in v4

interface IRenderWrapperArgs {
  children: React.ReactNode
  width?: number
  height?: number
}

type RenderWrapper = (args: IRenderWrapperArgs) => React.ReactElement

interface PlaceholderProps {
  aspectRatio?: number
  maxWidth?: number
  isDarkColorMode?: boolean
  isAdmin: boolean
}

Properties definition

Property	Definition
propName	The prop of the Brick component corresponding to this image.
alt	The fallback alternate text for the image when it isn't provided via the upload modal
maxWidth	This is the maximum width in pixel at which your image will be displayed. It is used to calculate the responsive images for normal and retina displays. The default value is 800.
noLazyLoad	Set to true to avoid the lazy load behaviour. Default is false.
aspectRatio	If you set an aspect ratio, the user will have a fixed-ratio selection mask to crop the uploaded image.
imageClassName	Optional className to apply to the <img> tag.
imageStyle	Optional style object to apply to the <img> tag.
sizes	Optional string to set the sizes attribute on the image for responsive images serving.
loading	The default is lazy. Optional prop to change the loading attribute on the image for native lazy loading. Usually you don't have to change the default behaviour.
renderWrapper	Optional render function for the wrapper you want around the image. You have children, width and height as arguments (width and height are from the image original size, useful to calculate aspect ratio).
useNativeLazyLoading	The default is true: if we detect browser support for native lazy loading, we don't use our lazy loading system, but we rely on the browser native one. If set to false, we always do the lazyloading with our component.
useWebP	The default is true: we create WebP images upon upload, keeping JPEG (or PNG if there is transparency) images as a fallback for browsers which don't support WebP. If set to false we don't create WebP images from the images you upload.
metaFieldName	Bind the text value to a page Meta field (2-way data binding)
customFieldName	Bind the text value to a page Custom field (2-way data binding)
placeholder	Function to customize the default image placeholder. It gets { aspectRatio, maxWidth, isDarkColorMode, isAdmin } as argument and should return a string URL. While the default placeholder is not rendered in the frontend if no image is uploaded (nothing is rendered), with a custom placeholder you need to explicitly avoid rendering if isAdmin is false, if you would like to avoid rendering the placeholder on the frontend.
readonly	false by default. If true, the image is read-only, with no editing interface.
quality	Quality of the optimized image (applied to WEBP and JPEG images), default is 80.
DEPRECATED	The following properties still work but are deprecated
containerClassName	Optional className to apply to the image container (a thin wrapper created by React Bricks). DEPRECATED since 3.3.0: use renderWrapper instead.
containerStyle	Optional style object to apply to the image container. DEPRECATED since 3.3.0: use renderWrapper instead.
noWrapper	Optional flag to avoid the wrapping <div> around the image. Default is false. When set to true, the containerClassName and containerStyle do not apply. DEPRECATED since 3.3.0: now by default no wrapper is rendered.

Usage example

<Image propName="image" alt="Product" maxWidth="420" aspectRatio="1.33" />