Use the Image control

In this how-to, you'll learn when to use SideEditPropType.Image and how it differs from the visual <Image /> component.

The short version is:

• use the visual <Image /> component when editors should click the image directly in the page
• use the sidebar Image control when the image is more like a setting, such as a background image

Docs reference: Sidebar controls

A good use case: background images

Background images are the classic case for the sidebar image control.

Editors usually do not click on a CSS background in the page itself, so a sidebar picker is the better fit.

Example

import { Text, types } from 'react-bricks/rsc'
 
interface HeroBannerProps {
  title: types.TextValue
  backgroundImage: types.IImageSource
  overlay: boolean
}
 
const HeroBanner: types.Brick<HeroBannerProps> = ({
  title,
  backgroundImage,
  overlay,
}) => {
  return (
    <section
      className="rounded-2xl bg-cover bg-center p-16 text-white"
      style={{
        backgroundImage: backgroundImage?.src
          ? `url(${backgroundImage.src})`
          : undefined,
      }}
    >
      <div className={overlay ? 'bg-black/40 rounded-xl p-10' : ''}>
        <Text
          propName="title"
          value={title}
          placeholder="Hero title..."
          renderBlock={({ children }) => <h1 className="text-5xl">{children}</h1>}
        />
      </div>
    </section>
  )
}
 
HeroBanner.schema = {
  name: 'hero-banner',
  label: 'Hero Banner',
  getDefaultProps: () => ({
    title: 'A hero with a sidebar-managed background',
    overlay: true,
  }),
  sideEditProps: [
    {
      name: 'backgroundImage',
      label: 'Background Image',
      type: types.SideEditPropType.Image,
      imageOptions: {
        maxWidth: 1600,
        aspectRatio: 16 / 9,
      },
    },
    {
      name: 'overlay',
      label: 'Dark Overlay',
      type: types.SideEditPropType.Boolean,
    },
  ],
}

What imageOptions does

For sidebar image controls, you can set:

• maxWidth: the maximum useful width for the asset
• aspectRatio: a fixed crop ratio, such as 16 / 9 or 1

These options are especially helpful when:

• the image always appears in a fixed design slot
• you want more consistent crops across pages
• you want to avoid unnecessarily large uploads

When not to use the sidebar Image control

Do not use it for images that should be visually editable in place.

For example, if the editor is expected to click the image inside the page and immediately replace it, the visual <Image /> component is usually a better user experience.

Related reading: Add an editable image

A practical pattern

It is common to pair the sidebar image control with another prop such as:

• overlay
• backgroundPosition
• minHeight
• useBackgroundImage

That gives editors a small, controlled set of background-related choices without exposing raw CSS.

Summary

Use SideEditPropType.Image when the image behaves like a brick setting rather than like a visible, directly editable content element.