---
title: Use the Relationship control
category: Sidebar controls in depth
order: 7
status: published
summary: Use the Relationship control when editors need to connect a brick to one or more pages or entities of a given page type.
estimatedTime: 7 min
keywords: sideeditprops relationship page type entity references embedvalues multiple
---

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](https://docs.reactbricks.com/bricks/schema/side-edit-props/#relationship)

## 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:

```tsx
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:

```tsx
name: 'category'
```

you also get:

```tsx
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)](/how-tos/reuse-content-across-pages/reuse-a-fragment-embed)