---
title: "Consuming a content entity reference prop"
date: "2026-07-17T12:32:15+00:00"
summary: "Learn how to consume a content entity reference prop in Drupal Canvas components, including key naming rules, nested structures, and null handling."
image:
type: "page"
url: "/source-cms/consuming-content-entity-reference-prop"
id: "a1047781-436b-48d8-80c8-46b3de623bf9"
---
Table of contents will be added
This developer focused guide provides instructions for developers who write the code for a component that has a [Content entity reference prop](/source-cms/content-entity-reference-props "Content entity reference props").
Note
As Drupal Canvas does not display the data structure of the prop, ensure that you understand it precisely.
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: "…
",
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](https://3-rules-determine-keys).
To confirm any key, refer to the section on [inspecting the value](https://inspecting-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](https://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:
Dialog box selection
Key in the prop value
**Title**
`label`
**ID**
`id`
**Revision ID**
`revision`
**Content type**
`bundle`
**Published**
`published`
**Authored by**
`owner`
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`.
Important
To confirm the exact key of a field, inspect the value. Do not guess.
### [Property output formats](https://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](https://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 (
{image?.src && 
}
{label && {label}
}
{author?.label && By {author.label}
}
{body && }
);
};
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](/source-cms/adding-components-page "Adding components to 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](https://www.npmjs.com/package/@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
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.