Skip to content
Drupal Canvas

Code Components - Component metadata

When working with Code Components in a local codebase, component.yml files define component metadata. This follows the same metadata model as SDC component.yml files.

Code Component metadata can define props, slots, and examples. Prop schemas are limited to the types supported by the in-browser code editor.

Prop metadata

Section titled “Prop metadata”

Each prop corresponds to a JSON Schema definition.

Text

Section titled “Text”

Basic text input. Stored as a string value.

type: string
examples:
  - Hello, world!

Formatted text

Section titled “Formatted text”

Rich text content with HTML formatting support, displayed in a block context.

type: string
contentMediaType: text/html
x-formatting-context: block
examples:
  - <p>This is <strong>formatted</strong> text with HTML.</p>
Section titled “Link”

URL or URI reference for links to internal or external resources.

type: string
format: uri-reference
examples:
  - https://example.com

The format can be either uri, which accepts only absolute URLs, or uri-reference, which accepts both absolute and relative URLs.

Image

Section titled “Image”

Reference to an image object with metadata like alt text, dimensions, and file URL. Only the file URL is required to exist; all other metadata is always optional.

type: object
$ref: json-schema-definitions://canvas.module/image
examples:
  - src: >-
      https://images.unsplash.com/photo-1484959014842-cd1d967a39cf?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1770&q=80
    alt: Woman playing the violin
    width: 1770
    height: 1180

Video

Section titled “Video”

Reference to a video object with metadata like dimensions and file URL. Only the file URL is required to exist; all other metadata is always optional.

type: object
$ref: json-schema-definitions://canvas.module/video
examples:
  - src: https://media.istockphoto.com/id/1340051874/video/aerial-top-down-view-of-a-container-cargo-ship.mp4?s=mp4-640x640-is&k=20&c=5qPpYI7TOJiOYzKq9V2myBvUno6Fq2XM3ITPGFE8Cd8=
    poster: https://example.com/600x400.png

Boolean

Section titled “Boolean”

True or false value.

type: boolean
examples:
  - false

Integer

Section titled “Integer”

Whole number value without decimal places.

type: integer
examples:
  - 42

Number

Section titled “Number”

Numeric value that can include decimal places.

type: number
examples:
  - 3.14

List: text

Section titled “List: text”

A predefined list of text options that the user can select from.

type: string
enum:
  - option1
  - option2
  - option3
meta:enum:
  option1: Option 1
  option2: Option 2
  option3: Option 3
examples:
  - option1

The meta:enum property provides user-friendly labels for each enum value. The keys match the enum values, and the values are the display labels shown in the UI.

Enum values cannot contain dots.

List: integer

Section titled “List: integer”

A predefined list of integer options that the user can select from.

type: integer
enum:
  - 1
  - 2
  - 3
meta:enum:
  1: Option 1
  2: Option 2
  3: Option 3
examples:
  - 1

The meta:enum property provides user-friendly labels for each enum value. The keys match the enum values, and the values are the display labels shown in the UI.

Enum values cannot contain dots.

Content entity reference

Section titled “Content entity reference”

Reference to a selected Drupal content entity as a structured object. Use this when the component needs the editor to choose an entity and the component should receive selected entity fields together on one prop.

props:
  properties:
    featuredArticle:
      title: Featured article
      type: object
      $ref: json-schema-definitions://canvas.module/content-entity-reference
      x-allowed-entity-type-id: node
      x-allowed-bundle: article
dataDependencies:
  entityFields:
    featuredArticle:
      - ℹ︎␜entity:node:article␝title␞␟value
      - ℹ︎␜entity:node:article␝path␞␟alias

Content entity reference props must be optional: do not list them in required. Do not add examples; preview values are resolved from dataDependencies.entityFields.

Every content entity reference prop must include:

  • x-allowed-entity-type-id: the Drupal entity type, such as node
  • x-allowed-bundle: the Drupal bundle, such as article

Add dataDependencies.entityFields.<propName> with one or more expressions from .agents/drupal-canvas/content-entity-reference-expressions.json. If that file is missing, stale, or does not include the needed entity fields, run npx canvas agents-context cer-expressions to refresh the content entity reference expressions from the configured Canvas site.

All expressions for one content entity reference prop must target the same entity type and bundle. Do not infer the final component prop shape from expression names alone. After the component metadata exists locally, run npx canvas agents-context cer-preview <component> to inspect the resolved prop shape that component code should consume. Reference expressions can create nested objects and include metadata keys such as __type.

Slot metadata

Section titled “Slot metadata”

Slots are defined under the slots key. Each slot key becomes the slot name passed to the Code Component. The title is shown in Canvas, and examples provide preview content.

slots:
  content:
    title: Content
    description: Content to display below the greeting.
    examples:
      - <div>Example slot content</div>