Image

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

Required properties:

propName: the name of the prop
source: prop’s value (strictly needed only for RSC, but it’s avisable to always provide it for server componenents 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 to replace an image by opening a modal where editors 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.

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'