canvas_entity_reference

Canvas Entity Reference adds entity reference support to the Canvas component props system. It allows site builders to use taxonomy terms, nodes, users, and media as component properties inside the Canvas page builder using a simple x-entity-type annotation or legacy $ref in the component YAML. The module provides autocomplete selection, multi-value tags, per-prop bundle filtering, per-prop widget override, and optional auto-creation of new terms — all without custom field configuration or custom PHP code.

Taxonomy term — single value:
Taxonomy term — multi-value:
Node — returns label (string):
Node — returns entity ID (integer), for use with
entity_render():
Media — rendered in template via
entity_render():
User — returns display name (string):
Optionally define maxItems to limit cardinality on array props.

  {% if hero_image > 0 %}
    {{ entity_render('media', hero_image, 'default') }}
  {% endif %}
  

Features

• Declarative schema matching — Add x-entity-type: taxonomy_term (or node, user, media) to any component prop and it automatically becomes an entity reference autocomplete field in the Canvas editor. The legacy $ref URI is still supported for taxonomy terms.
• Single and multi-value support — Use a plain type for single entity references or type: array with items for comma-separated multi-value tags. Cardinality is derived from schema settings such as maxItems.
• x-entity-field — Control which field on the referenced entity is returned as the prop value. Defaults to the entity label.
  Set to an ID key (nid, tid, mid, uid) to get a numeric entity ID instead — useful when pairing with entity_render().
• x-entity-type-bundles — Restrict which bundles appear in the autocomplete for a specific prop using a comma-separated list, without touching the global settings page. Works for all entity types.
  For taxonomy terms, overrides the global vocabulary setting.
• x-entity-widget — Override the widget plugin per-prop without changing the global setting. Useful for contrib widgets such as Tagify or Entity Browser, provided those modules register the required Canvas transform metadata.
• entity_render() Twig function — Render a referenced entity in any view mode directly from the component Twig template.
  Pair with x-entity-field: mid to render media images, or x-entity-field: nid to render nodes.
• Auto-creation of terms — Optionally allow users to create new taxonomy terms directly from the autocomplete field when a term does not already exist.
• Configurable target vocabularies — Restrict which vocabularies are available globally via the settings page, or override per-prop using x-entity-type-bundles.
• Configurable widget — Choose between Autocomplete and Autocomplete (tags) globally via the settings page, or override per-prop using x-entity-widget.
• Canvas live preview integration — Includes custom Canvas transforms that normalize Drupal autocomplete values (Label (ID)) into numeric entity IDs for live preview while preserving readable labels in the editor.
• Example components included — Ships with 7 test SDCs:
  1. Test: Media Reference
  2. Test: Multi-value & Taxonomy Term (x-entity-type)
  3. Test: Node Reference (numeric ID)
  4. Test: Node Reference (title)
  5. Test: User Reference
  6. Test: Bundle Filter (x-entity-type-bundles & x-entity-widget)
  7. Example Taxonomy Card

Post-Installation

1. Enable the module
   Enable at /admin/modules or with Drush:
   drush en canvas_entity_reference
2. Configure settings (optional)
   Go to: /admin/config/content/canvas-entity-reference
   • Select which taxonomy vocabularies are available for entity reference props globally. Leave unchecked to allow all.
   • Enable or disable automatic creation of new taxonomy terms.
   • Select the default widget for single-value props (Autocomplete or Autocomplete tags).
3. Declare entity reference props in your component YAML
   Use the x-entity-type annotation as the primary approach. The legacy $ref URI for taxonomy terms is still supported.

   Single-value taxonomy term:

   props:
       type: object
       properties:
         category:
           type: ['string', 'null']
           title: Category
           x-entity-type: taxonomy_term

   Single-value node (title):

   props:
       type: object
       properties:
         article:
           type: ['string', 'null']
           title: Related Article
           x-entity-type: node

   Node — return numeric ID for use with entity_render():

   props:
       type: object
       properties:
         article_id:
           type: ['integer', 'null']
           title: Related Article
           x-entity-type: node
           x-entity-field: nid

   Restrict to specific bundles:

   props:
       type: object
       properties:
         featured:
           type: ['string', 'null']
           title: Featured Article
           x-entity-type: node
           x-entity-type-bundles: 'article'

   Multi-value with maxItems:

   props:
       type: object
       properties:
         tags:
           type: array
           title: Tags
           maxItems: 5
           items:
             type: ['string', 'null']
             x-entity-type: taxonomy_term

   Legacy $ref syntax (taxonomy term only):

   props:
       type: object
       properties:
         category:
           type: string
           title: Category
           $ref: json-schema-definitions://canvas_entity_reference.module/taxonomy-term-reference

4. Use inside Canvas
   Open a Canvas page containing your component. The property will render as a Drupal entity reference autocomplete field. Users can search existing entities or create new taxonomy terms (if enabled).
5. Try the 7 included test components
   All test components are grouped under Entity Reference Tests in the Canvas component picker and demonstrate the full range of annotations and entity types:
   1. Test: Media Reference
   2. Test: Multi-value & Taxonomy Term (x-entity-type)
   3. Test: Node Reference (numeric ID)
   4. Test: Node Reference (title)
   5. Test: User Reference
   6. Test: Bundle Filter (x-entity-type-bundles & x-entity-widget)
   7. Example Taxonomy Card

Additional Requirements

• Canvas (^1) —
  Required. This module extends Canvas component props with entity reference support.
• Drupal Core ^10.3 || ^11

Recommended modules/libraries

• Canvas — Provides the form state and live preview integration used by this module.
• Twig Tweak —
  Useful for advanced Twig rendering patterns alongside entity_render().

Similar projects

• sdc_entity_mapping — Provides entity-to-SDC prop mapping via configuration. It takes a different approach: you define explicit field mappings per entity type/bundle rather than using autocomplete widget integration with Canvas props. If your use case is rendering entities in specific view modes, that module may be a better fit.
• Canvas core — content-entity-reference prop shape (https://git.drupalcode.org/project/canvas/-/commit/29e44233fe353fda804eb...)
  Canvas core added a built-in content-entity-reference well-known prop shape for code components (JavaScript/React). Entity type and bundle are configured via dataDependencies.entityFields in the JS component config and resolved at render time. This approach does not apply to Twig/block components and has no autocomplete widget or non-JS fallback — the gap this module addresses.
• For non-Canvas use cases such as Layout Builder or Paragraphs, use Drupal core Entity Reference fields.

Supporting this Module

This module is community maintained. Contributions, bug reports, and feature requests are welcome via the issue queue:
Canvas Entity Reference issue queue.

Community Documentation

This module is community maintained. Contributions, bug reports, and feature requests are welcome via the issue queue: Canvas Entity Reference issue queue.

Documentation and walkthrough videos are coming soon.
If you create tutorials, blog posts, or videos about this module, please open an issue and we will gladly link them here.