Image

The Image component enables content editors to upload/select and modify images.

Required properties:

• propName: the name of the prop
• source: prop value. It is strictly required only for RSC, but we recommend always providing it for Server Components compatibility.

Other frequently used props:

• aspectRatio: forces editors to crop an image with a fixed aspect ratio (e.g. 16 : 9)
• alt: fallback alternate text, used if editors don’t provide ALT text via the interface
• maxWidth: instructs React Bricks image optimization on the maximum displayed size for this image
• quality: sets the image compression quality (default 80)
• sizes: provides fine-tuned image direction via the “sizes” attribute
• imageClassName: class name applied to the rendered image

Usage example

import { types, Image } from 'react-bricks/frontend'

interface MyBrickProps {
  image: types.IImageSource
}

const MyBrick: types.Brick<MyBrickProps> = ({ image }) => (
  ...
  <Image
    propName="image"
    source={image}
    alt="Product"
    maxWidth="650"
    aspectRatio="1.33"
  />
  ...
)

MyBrick.schema = { ... }

export default MyBrick

Rendering

• On the frontend, the Image component displays a responsive, optimized image with progressive loading (lazy load).
• In the Admin interface, it allows editors to replace an image by opening a modal where they can:
  • Replace an image from the media library, Unsplash, upload, or URL
  • Apply transformations (crop, rotate, flip)
  • Set the alternate text (ALT), SEO-friendly name (for the image URL), and priority for images above the fold

Optimization

To boost performance and SEO, upon upload, React Bricks will:

• Create responsive optimized images
• Create the srcSet for optimal image selection on the frontend
• Create a lightweight blurred placeholder for progressive loading when the native lazy loading is unavailable
• Serve images from a global CDN
• Enforce SEO-friendly name via proper rewrite rules

Readonly

To render an image loaded in React Bricks as read-only, add the readonly flag.

A common use case is rendering blog post thumbnails in a list of posts loaded via the fetchPages function. You can render a thumbnail for each post using <Image readonly source={...}>.

Bind to Meta data or Custom fields

As for Text and RichText, you can also bind an image to a page’s custom field or meta image by replacing propName with customFieldName or metaFieldName.

This creates a two-way data binding between the visual editing component and the images set via sidebar controls in the “Page” tab.

Practical how-to

For a step-by-step guide, see Add an editable image.

Properties

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

// For both editable and readonly images
interface SharedImageProps {
  readonly?: boolean
  source?: types.IImageSource
  alt: string
  noLazyLoad?: boolean
  imageClassName?: string
  imageStyle?: React.CSSProperties
  quality?: number
  sizes?: string
  loading?: 'lazy' | 'eager'
  renderWrapper?: ({
    children: React.ReactNode
    width?: number
    height?: number
  }) => React.ReactElement
  useNativeLazyLoading?: boolean
  useWebP?: boolean
  placeholder?: (props: {
    aspectRatio?: number
    maxWidth?: number
    isDarkColorMode?: boolean
    isAdmin: boolean
  }) => string
}

// For editable images
interface EditableImage extends SharedImageProps {
  readonly?: false
  propName?: string
  metaFieldName?: 'image'
  customFieldName?: string
  aspectRatio?: number
  maxWidth?: number
}

// For readonly images
interface ReadOnlyImage extends SharedImageProps {
  readonly: true
  source: types.IImageSource
}

/**
 * Props for Image
 */
type ImageProps = EditableImage | ReadOnlyImage

Properties definition

Property	Definition
propName	The prop of the Brick component corresponding to this image.
source	The value of the prop for this image. Required for Server Components, but always recommended for RSC compatibility
alt	The fallback alternate text for the image when not provided via the upload modal
maxWidth	The maximum width in pixel at which your image will be displayed. Used to calculate the responsive images for normal and retina displays. Default value is 800.
noLazyLoad	Set to true to avoid lazy loading. Default is false.
aspectRatio	If set, provides 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	Optional prop to change the loading attribute for native lazy loading. Default is lazy. Usually, the default behaviour suffices.
renderWrapper	Optional render function for a custom wrapper around the image. Provides children, width and height as arguments (width and height are from the original image size, useful for calculating aspect ratio).
useNativeLazyLoading	The default is true: if browser support for native lazy loading is detected, it is used instead of our lazy loading system. Set to false to always use the custom lazy loading.
useWebP	The default is true: creates WebP images upon upload, keeping JPEG (or PNG for transparency) as fallbacks without WebP support. Set to false to skip WebP creation.
metaFieldName	Binds the image value to a page Meta field (two-way data binding)
customFieldName	Bind the image value to a page Custom field (two-way data binding)
placeholder	Function to customize the default image placeholder. Receives { aspectRatio, maxWidth, isDarkColorMode, isAdmin } and should return a string URL. For custom placeholders, explicitly avoid rendering if isAdmin is false to prevent frontend display.
readonly	Default is false. If true, the image is read-only, without an 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 for the image container (a thin wrapper created by React Bricks). DEPRECATED since 3.3.0 as no wrapper is created anymore. Use renderWrapper instead.
containerStyle	Optional style object to apply to the image container. DEPRECATED since 3.3.0 as no wrapper is created anymore: use renderWrapper instead.
noWrapper	Optional flag to avoid the wrapping <div> around the image. Default is false. DEPRECATED since 3.3.0 as no wrapper is created anymore.

Usage with Server Components

When working with Server Components, you need to import from 'react-bricks/rsc':

import { types, Image } from 'react-bricks/rsc'