This developer focused guide provides instructions for developers who write the code for a component that has a Content entity reference prop. 

The value is an object

A content entity reference prop delivers a plain JavaScript object. This object contains only the selected fields.

For example, a prop named article targets Content → Article. 

You select these fields:

• Title
• Body → Processed text
• Cover Image → Name
• Cover Image → Image → Image URL
• Cover Image → Image → Alternative text
• Author profile → Title

The component receives the following output:

{
  __type: "article",
  label: "Template verification article",
  body: "<p>…</p>",
  cover_image: {
    __type: "image",
    label: "acme.png",
    media_image: {
      alt: "Acme",
      src: "/sites/default/files/2025-07/acme.png?alternateWidths=…"
    }
  },
  author_profile: {
    __type: "person",
    label: "Ada Lovelace"
  }
}

Two details in the object require attention:

• Mismatched key names: Key names do not always match the labels in the field picker. For example. the key for Title is label, not title. 
• Nested data structures: The cover image is not a flat value. It is a reference to a media item. Therefore, the data arrives in a nested structure. The image resides one level further down, under the image field of the media item.

To understand both concepts, review the following three rules. 

To confirm any key, refer to the section on inspecting the value.

Three rules determine the keys

Three rules determine the keys in the delivered JavaScript object. 

• Content identifiers: A field with a defined role, such as a title or an author, receives a new name.
• Property output formats: A single property provides a string value. Multiple properties provide an object.
• Nested references: A field on referenced content nests under the parent reference key.

Content identifiers: A field that identifies the content receives a new name

Some fields have a defined role for the content type, such as the title or the author. Those fields arrive under the role name rather than the field name. For Content, the fields map as follows:

Other content entity types follow the same rule. The Name of a media item also arrives as label. The cover_image.label property in the previous example demonstrates this behavior. The Name of a taxonomy term follows the same pattern.

Every other field keeps its original name. Body arrives as body, Cover Image as cover_image, and the Image of the media item as media_image. 

Property output formats: One property provides a value. Several properties provide an object.

To produce body as a string, select only Body → Processed text.

To produce the image field as an object with the selected properties as keys, select both Image URL and Alternative text on an image field:

media_image: { src: "/sites/default/files/…", alt: "Acme" }

Nested references: Follow a reference to produce a nested object

When you select a field on referenced content, the system nests it under the key of the field that points to it. The nested object carries its own __type.

Images typically arrive in this format. A Cover Image field does not hold an image directly. It references a media item. Therefore, when you select the Image → Image URL of the media item, the system produces:

cover_image: {
  __type: "image",
  media_image: { src: "/sites/default/files/…" }
}

The same rule applies to any reference. When you select Author profile → Title, it produces author_profile: { __type: "person", label: "Ada Lovelace" }.

Select only single-value fields

A field that holds more than one value does not appear in the Content Relationship dialog box. The fields of the referenced content also do not appear. On an Article, fields such as Tags, Categories, and Related articles hold many values. Therefore, they do not appear in the list.

If an expected field does not appear, verify if the field configuration holds more than one value.

Every object carries __type

Each object at the top level and at every nested level includes a __type key. This key identifies the content type it represents. Use it when you must branch on the content type. Treat it as reserved.

Handle missing values

Two independent elements can be missing. A robust component checks both elements.

• The entire prop can be null. This occurs when no content is referenced, when the referenced content is deleted, or when a content template maps an empty reference field. Never assume that the object exists.
• An individual field can be null. An article with no cover image yields cover_image: null instead of an object with empty values. A field can also change shape or disappear if the content type configuration changes later.

Nested structures compound this behavior. To reach an image, you must pass through the reference, the media item, and the image field. Any of these elements can be missing.

Use optional chaining at every level.

const ArticleCard = ({ article }) => {
  if (!article) {
    return null;
  }
  const { label, body, cover_image: cover, author_profile: author } = article;
  const image = cover?.media_image;
  return (
    <article>
      {image?.src && <img src={image.src} alt={image.alt ?? ''} />}
      {label && <h3>{label}</h3>}
      {author?.label && <p>By {author.label}</p>}
      {body && <div dangerouslySetInnerHTML={{ __html: body }} />}
    </article>
  );
};
export default ArticleCard;

Inspecting the value

Because the interface does not display key names, confirm them when you render the value. Temporarily replace the output of the component with the value itself:

const Component = ({ article }) => JSON.stringify(article, null, 2);
export default Component;

Then:

1. Place the component on a page.
2. Reference a piece of content in the field of the prop.
3. Read the resolved object in the page preview.

The preview displays exactly what your code receives. This includes __type, the renamed keys, and any nested structures. Restore the real output of your component after you finish.

Perform this action whenever you add or change a field selection. Ensure that you do this before you write code against a field that you added to the content type.

Print the value from a terminal

If you work with a local codebase, print the resolved value. With this approach, you do not need to place the component on a page. This method is faster than the page preview when you iterate on a field selection.

The command reads the component from your local project and requests the site to resolve the fields against a real piece of content. Therefore, a component that you author in the browser remains invisible to the command until you pull the component to your local environment.

To print the resolved value from a local codebase:

1. Install the Drupal Canvas CLI.
2. Configure the CLI to point to your site.
3. Set the CANVAS_SITE_URL, CANVAS_CLIENT_ID, and CANVAS_CLIENT_SECRET variables. 
4. Obtain the client ID and secret from an OAuth consumer on the site.
5. Pull your components into the local project:

npx canvas pull

4. Print the resolved value for one component:

npx canvas agents-context cer-preview <component-id>

The output is the same object that your code receives. This includes __type, the renamed keys, and any nested structures.

If the command reports that the component is missing, it searches in your local project instead of the site. Run the npx canvas pull command first.

Information absent from the code editor preview

The Preview pane inside the code editor does not resolve content entity reference props. The pane has no selected content. Therefore, the prop arrives as an empty string instead of an object or a null value.

This behavior has two consequences:

• You cannot use the preview of the code editor to discover the shape of the value. Use the page preview instead, as described previously.
• Code that assumes the prop is either an object or null might render differently in the preview of the code editor than it does on a page. Do not treat the preview of the code editor as a test for your null handling.

Content hidden from the viewer

The system resolves field values against the permissions of the person who views the page. The system checks permissions for every piece of content that the prop reaches. This includes content reached when you follow a reference.

If a viewer does not have permission to view the referenced content, the component does not silently omit the field. Instead, the page fails to render that component. This behavior is critical when you follow a reference into non-public content, such as the account of the author who created an article. Select fields from referenced content only when every viewer has permission to view that content.

Reference content to tie the component to the content type

When you select fields, Drupal Canvas records the content type and those specific fields as component requirements. A component that reads the body and image of an article requires a site where the Article type contains those fields with the exact configuration.

The practical effects include:

• The component might not be reusable on another site with different content types.
• If an administrator removes or reconfigures a field that the component reads, the output of the component changes or the field arrives as null.

Select only the required fields.

Consuming a content entity reference prop

{
  __type: "article",
  label: "Template verification article",
  body: "<p>…</p>",
  cover_image: {
    __type: "image",
    label: "acme.png",
    media_image: {
      alt: "Acme",
      src: "/sites/default/files/2025-07/acme.png?alternateWidths=…"
    }
  },
  author_profile: {
    __type: "person",
    label: "Ada Lovelace"
  }
}

media_image: { src: "/sites/default/files/…", alt: "Acme" }

cover_image: {
  __type: "image",
  media_image: { src: "/sites/default/files/…" }
}

const ArticleCard = ({ article }) => {
  if (!article) {
    return null;
  }
  const { label, body, cover_image: cover, author_profile: author } = article;
  const image = cover?.media_image;
  return (
    <article>
      {image?.src && <img src={image.src} alt={image.alt ?? ''} />}
      {label && <h3>{label}</h3>}
      {author?.label && <p>By {author.label}</p>}
      {body && <div dangerouslySetInnerHTML={{ __html: body }} />}
    </article>
  );
};
export default ArticleCard;

const Component = ({ article }) => JSON.stringify(article, null, 2);
export default Component;

npx canvas pull

npx canvas agents-context cer-preview <component-id>