--- title: "Content entity reference props" date: "2026-07-17T12:06:02+00:00" summary: "Configure content entity reference props in Drupal Canvas to display live, connected data from existing content in your code components." image: type: "page" url: "/acquia-source/content-entity-reference-props" id: "b83b4331-9c85-43e1-937f-2cc52d91d174" --- Table of contents will be added This document provides instructions for configuring content entity reference props. Content entity reference props enable a code component to display live data from an existing piece of content. A content author selects the content to reference, and the component receives the fields selected during the build process. When the referenced content changes, the component reflects the change without data re-entry. Use a content entity reference prop when a component must present content that already exists on the site, such as a card for an article, a liftup for a product, or a related-content teaser. Unlike a text prop, the value does not copy into the component. It stays connected to the source content. **Prerequisites** * Access to Drupal Canvas with permission to create and edit code components. For more information, visit [Managing permissions](https://docs.acquia.com/acquia-source/managing-permissions) * At least one content type, media type, taxonomy vocabulary, or other content entity bundle to reference. * The fields to display on the component must already exist on that bundle. Understanding content entity reference props -------------------------------------------- A content entity reference prop has two parts: * **Allowed type**: The single entity type and bundle a content author is permitted to link to.  * For example, **Content** restricted to the **Article** bundle.  * **Entity fields**: The specific fields and field properties of that bundle the component receives.  * Examples include the title, the processed text of the body, the image URL, and alternative text. Select both parts to define the prop. The content author only selects which entity to link to. This separation keeps the data contract of the component stable while it provides authors full control over curation. Adding a content entity reference prop -------------------------------------- 1. [Access your site](https://docs.acquia.com/node/69836#access-a-site). 2. On the top right, click **Edit** to open Drupal Canvas. 3. In the left toolbar, click the **Code ** icon to open the code-based components menu. 4. Select the code component to edit. The system opens the Preview and Component data panels for the component. 5. In the Component data pane, on the **Props** tab, click **+ Add**. For more information, visit [Props](https://docs.acquia.com/acquia-source/props). 6. Enter a Prop name. 7. From the **Type** list, select **Content entity reference**. 8. Select **Add type**.  The Content Relationship dialog box opens. 9. Select an entity type from the **Select entity type** list. 10. Select a bundle from the **Select bundle** list. 11. Click **Continue**. The dialog box lists every field on that bundle. 12. Select the checkbox for each field or field property the component needs. To reach the properties of a field, expand the field.  For example, expand **Body** to select **Processed** **text**. 13. Select **Save**. The prop displays the entity type, the bundle, and an **Entity fields** count. 14. _(Optional)_:  1. Click **Expand fields** to review the selected fields. 2. Click **Edit** to change the selection. Selecting fields and following references ----------------------------------------- The Content Relationship dialog box categorizes fields into three groups: Field Type Description Example **Fields with a single property** To provide the component a single value, select the property of the field. Title **Fields with several properties** To provide the component an object, select more than one property. Image fields expose File ID, Alternative text, Title, Width, Height, and Image URL. **Reference fields** To select fields on the referenced content, expand a reference field. Reference fields, such as Cover Image, Author profile, and Authored by, display a badge that identifies the associated content type, for example, Image, Person, or User. For example: Images are commonly reference fields. A **Cover Image** field points to a media item and does not contain an image directly.  To reach the image in this example: 1. Add a content entity reference prop. 2. Expand **Cover Image**. 3. Expand the **Image** field of the media item. 4. Select **Image URL** and **Alternative text**. 5. To produce a nested object in the prop value, select fields on referenced content. ### Excluded multi-value fields The dialog box displays only fields that hold a single value. A reference follows only to a single-value field. Fields such as **Tags**, **Categories**, and **Related articles** hold many values. Therefore, these fields do not appear in the dialog box. Note If an expected field does not appear, verify the configured quantity of values for that field. Constraints ----------- Content entity reference props behave differently from other prop types. The Props tab reflects this behavior and hides controls that do not apply. Constraint Description **Targets one entity type and bundle** To offer authors a choice between bundles, define more than one prop or place more than one component. **Holds a single value** The **Allow multiple values** option is not available. To display several entities, add several props or place the component several times. **Cannot be required** The **Required** switch is not available because the referenced entity is subject to deletion or might never be selected. The component must handle a missing value. **Cannot have an example value** The **Example value** field is not available. Preview values resolve from the real content the author selects. Referencing the entity as a content author ------------------------------------------ After the [component is placed on a page](https://docs.acquia.com/acquia-source/adding-components-page), the prop displays as an autocomplete field labeled with the title of the prop. Enter part of the content title to search, then select a result. Authors can select only content of the configured entity type and bundle. In a content template, connect a content entity reference prop to structured data instead of a manually selected entity: * **Entity reference field**: Connect the prop to an entity reference field on the template entity. For example, a Related articles field on an Article template can populate the prop of an Article card component. * **Template host entity**: Connect the prop to the host entity of the template when the prop targets the same entity type and bundle as the template itself. For example, an Article template can pass its own article into an Article card component. Verifying the result -------------------- [Place the component on a page](https://docs.acquia.com/acquia-source/adding-components-page), reference an entity, and confirm the component renders the data of that entity. Change a field on the referenced entity and reload the page. The component reflects the new value, because the data resolves at render time instead of at the time of creation.