Components

Canvas Headless is an experimental feature

Canvas Headless may change or be removed without notice. It is off by default: enable it per site under Configurations > Experimental features before following the steps on this page.

Goal: know how the components editors place on Drupal Canvas pages are created, identified, and kept in sync when your app is the renderer.

What you’ll have when you’re done

• A working model of where components live in the app, what gives one its identity, and when the site learns about it.
• The rules that decide whether a component is offered for placement, and who is allowed to change what.

Prerequisites

• An app registered with your site, from the quickstart; its component directory already ships a working set (Hero, Card, Accordion, and more).

Steps

1. Know where components live. componentDir in canvas.config.json at the project root is the single source: components in the Next.js template, src/components in Astro, app/components in Nuxt. Each component is a directory holding its component.yml (metadata), source file, and CSS file, the shape npx canvas scaffold writes in the quickstart’s component scaffold step. An app component you already have becomes a Canvas component by gaining a component.yml beside it.

2. Give each component its identity.

   Yourself

   machineName in component.yml is the component’s identity in Canvas and the key your app’s generated registry renders by. The scaffolder writes the placeholder hello-world into every new component, so the second scaffold collides with the first until you change it. machineName does not have to match the directory name, but a name that does is easier to live with. Change machineName later and Canvas treats it as a different component: the new name registers, and the old entry is deactivated.

   With an AI agent

   Hand your agent this page’s Markdown export (the View as Markdown control at the top) for the identity and status rules, then the edit:

   In components/<name>/component.yml set machineName to <name> and status: true.
   machineName is the component's identity; renaming it later registers a new
   component and deactivates the old one.

3. Decide what editors can place. status: true offers the component for placement; a component left at the scaffolder’s status: false still synchronizes, and the site records it, but the library does not offer it. Nobody can rename an external component or flip its status from the editor: its identity belongs to the app that implements it, so both changes happen in component.yml.

4. Let synchronization do the rest. There is nothing to push. Canvas reads your app’s component metadata endpoint when the editor loads and registers every component it finds, so a reload after a change is what publishes it to the library. The props declared in a component’s component.yml appear as editable fields in the editor’s right-hand panel when that component is placed. Components that already exist on the site come the other way: npx canvas pull brings them into the app’s codebase in the same format.

When something goes wrong

A component is missing from the library

check its component.yml. status left at false registers without offering; machineName left at hello-world collides with the previous scaffold. Fix the file and reload the editor, since components synchronize when it loads.

Next steps

• Component development guide: the authoring model itself: props as JSON Schema, slots, styling, and composition.
• Prop type declarations: the exact schema that declares each prop type the editor offers, single- and multi-value.
• First fetch: the advanced path, when a component’s page is not enough and you need the content as data.