Components in a Canvas Headless app

In a Canvas Headless site, the components editors place in Canvas live in your front-end codebase, not in Drupal. This page covers how a component becomes available in the editor, what decides its identity, and how changes reach the site.

Goal

A component from your app that editors can place on Canvas pages, with props they can edit, and a clear rule for renaming or retiring it. To build a component inside Drupal with the in-browser code editor instead, read the Drupal Canvas documentation.

Prerequisites

• An app registered with Canvas and showing Ready, from the Canvas Headless quickstart.
• How components are synced, from How Canvas Headless preview works.

Steps

1. Put the component in the component directory

componentDir in the app’s canvas.config.json sets the one directory Canvas reads components from. The templates use components (Next.js), src/components (Astro and TanStack Start), or app/components (Nuxt). Each component is a directory placed directly inside componentDir, holding:

• component.yml: the metadata Canvas reads.
• The source file, such as index.jsx.
• An optional CSS file.

npx canvas scaffold --name <name> writes this shape for a new component. To turn a component you already have into a Canvas component, move it into its own directory under componentDir and add a component.yml beside it.

2. Set the identity and status

name: Promo banner
machineName: promo-banner
status: true

• name is the label editors see in the component library.
• machineName is the component’s identity. Canvas stores placements by it, and your app’s generated registry renders by it. It does not have to match the directory name, but matching names are easier to maintain. Every scaffolded component starts as hello-world; when two components share a machine name, Canvas keeps the first one it receives and skips the other.
• status: true offers the component in the library. With status: false, Canvas still registers the component but editors cannot place it.

Editors and site administrators cannot rename an external component or change its status in Drupal: the app that implements the component owns both, through component.yml.

3. Declare props and slots

Props are JSON Schema definitions under props.properties. The format follows the props schema of a single-directory component’s component.yml. Each prop becomes a field in the editor’s right-hand panel when the component is placed:

props:
  properties:
    heading:
      type: string
      title: Heading
      examples:
        - Spring sale
    link:
      type: string
      format: uri-reference
      title: Link
      examples:
        - /sale
slots:
  content:
    title: Content

Canvas supports text, formatted text (contentMediaType: text/html), links, images, videos, documents, booleans, integers, numbers, and lists. The component metadata reference lists the schema for each type. Slots let editors place other components inside this one; each slot key becomes a prop of the same name in your component.

4. Reload the editor

There is nothing to push. Each time someone with the Administer Canvas Headless frontends permission loads the Canvas editor, it reads your app’s /api/canvas/components endpoint and registers or updates every component it finds. Editors without that permission do not trigger a sync. Reload the editor as an administrator after changing a component.yml, and after every deployment that ships new or changed components.

Verify

Reload the Canvas editor and open the component library. Promo banner is listed. Drag it onto a page: your app renders it in the preview frame, and Heading and Link appear in the right-hand panel.

Variations

Rename a component

Changing machineName creates a new component: Canvas registers the new name and deactivates the old entry. Settle the machine name before editors start placing the component.

Bring existing site components into the app

Components that editors or developers built in Drupal with the in-browser code editor can move into your codebase with the Canvas CLI. npx canvas pull downloads them into componentDir in the same format. The CLI authenticates through the canvas_oauth submodule; the CLI documentation covers the login and client-credentials options.

Related

• Canvas Headless quickstart scaffolds an app and places the first component.
• How Canvas Headless preview works explains how the app renders the component tree.
• Single-directory components use the same component.yml prop format for Drupal-rendered themes.