canvas_entity_reference

Canvas Entity Reference adds taxonomy term entity reference support to the Canvas component props system. It allows site builders to use taxonomy terms as component properties inside the Canvas page builder using a simple JSON Schema $ref. The module provides autocomplete selection, multi-value tags, and optional auto-creation of new terms — all without custom field configuration or custom PHP code.

Features

• Declarative schema matching — Add a single $ref to a component prop in your JSON Schema and it automatically becomes a taxonomy term autocomplete field in the Canvas editor.
• Single and multi-value support — Use type: string for single term references or type: array with items for comma-separated multi-value tags. Cardinality is derived from schema settings such as maxItems.
• 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 for entity reference props or allow all vocabularies.
• 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 component included — Ships with an example-taxonomy-card Single Directory Component demonstrating single and multi-value taxonomy term references.

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. Leave unchecked to allow all.
   • Enable or disable automatic creation of new terms.
3. Use the provided JSON Schema reference
   Add the following $ref in your component schema:

   Single-value example:

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

   Multi-value example:

   props:
     type: object
     properties:
       tags:
         type: array
         title: Tags
         items:
           type: string
           $ref: json-schema-definitions://canvas_entity_reference.module/taxonomy-term-reference

   Optionally define maxItems to limit cardinality.

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 taxonomy terms or create new ones (if enabled).
5. Try the example component
   The included example-taxonomy-card component demonstrates taxonomy term references with title, description, tags, and links.

Additional Requirements

• Canvas (^1) — Required. This module extends Canvas component props with entity reference support.
• Drupal Core Taxonomy (drupal:taxonomy) — Required for taxonomy term storage and autocomplete.
• Drupal Core ^10.3 || ^11

Recommended modules/libraries

• Canvas — Provides the form state and live preview integration used by this module.
• Additional entity reference target types (nodes, users, media, etc.) may be added in the future via contributed extensions.

Similar projects

• There are currently no dedicated modules providing entity reference integration for Canvas component props.
• 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

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.