Use the Relationship control

In this how-to, you'll learn how to use SideEditPropType.Relationship.

This control lets editors choose a page or entity of a specific pageType, creating a structured relationship instead of typing IDs manually.

Docs reference: Sidebar controls

When Relationship is useful

Use it when a brick should point to:

• a category entity
• a related article
• a featured product
• a reusable fragment

This is much safer than asking editors to type a slug or an ID.

Example

Here is a brick that lets editors choose one related category entity:

import { Text, types } from 'react-bricks/rsc'
 
interface RelatedCategoryProps {
  title: types.TextValue
  category?: string
  category_embed?: {
    name?: string
    slug?: string
  }
}
 
const RelatedCategory: types.Brick<RelatedCategoryProps> = ({
  title,
  category_embed,
}) => {
  return (
    <section>
      <Text
        propName="title"
        value={title}
        placeholder="Section title..."
        renderBlock={({ children }) => <h2>{children}</h2>}
      />
 
      {category_embed ? (
        <p>Related category: {category_embed.name}</p>
      ) : (
        <p>No category selected yet.</p>
      )}
    </section>
  )
}
 
RelatedCategory.schema = {
  name: 'related-category',
  label: 'Related Category',
  getDefaultProps: () => ({
    title: 'Browse by category',
  }),
  sideEditProps: [
    {
      name: 'category',
      label: 'Category',
      type: types.SideEditPropType.Relationship,
      relationshipOptions: {
        references: 'category',
        multiple: false,
        embedValues: true,
      },
    },
  ],
}

The key relationshipOptions

You configure the control with:

• references: the name of the referenced pageType
• multiple: whether editors can choose one or many
• label: optional custom label for the internal selector
• embedValues: whether to also expose the related page values in {name}_embed

embedValues: true vs false

If embedValues is false, the prop gives you only the related item ID.

If embedValues is true, React Bricks also gives you a companion prop named {name}_embed.

So with:

name: 'category'

you also get:

category_embed

That is useful when the brick needs to render related data immediately, such as the category name.

Single vs multiple relationships

Use multiple: false when the brick points to one item, such as:

• one category
• one author
• one featured article

Use multiple: true when editors should choose many related items, such as:

• related products
• featured posts
• linked resources

A very common use case: embeds

Relationship is also the foundation for custom embed-like bricks that reference a specific entity or page type.

Related reading: Reuse a fragment (embed)