Canvas Visual Page Building

Drupal’s strength is structured content: typed fields, entity references, revisions and fine-grained access control. Its traditional weakness is page composition by non-developers. Core’s Layout Builder places blocks and fields in sections and is still part of core, but it works on one entity at a time or on a view mode, has no concept of a reusable, typed component with its own properties, and edits blocks through modal forms that are not a visual preview. Contributed alternatives (Paragraphs, Bootstrap-style layout modules, Panels) each solve one part of the problem and tie content to their own data model.

Canvas is the Drupal community’s answer. It aims at four things, in the words of the project page: reusable components across channels, large-scale content management that keeps Drupal’s structured data and access control, support for both coupled and headless contexts from one CMS, and large-scale design changes such as rebranding. In practice it provides:

Who uses it: editors compose pages; site builders curate the library and build content templates; themers provide SDCs; front-end developers write code components; back-end developers add block plugins and integrations.

A short history helps when reading tutorials. Canvas 1.0 (December 2025) was the first stable release and defined the editing model; 1.3 let code components import npm packages and added the push and pull CLI commands and TypeScript; 1.8 enabled translation support without a feature flag and added the Entity Reference prop type for code components; 1.10 added editable patterns and the configurable AI settings form; 1.11 added page templates and the Document prop type; 1.12 added Brand Kit and SVG support.

Because the module moves quickly, review the release notes before every minor update, and re-export configuration after updating (see Deployment and configuration).

On a Drupal CMS 2.x site Canvas is already installed. On a core project, add and enable it with Composer and Drush:

canvas:doctor is a health-check command that arrived with Canvas 1.9; run it after installing and after updating to find configuration that Canvas cannot render. Canvas needs Drupal 11.3 or later, so a Drupal 10 site must first be upgraded (see Upgrading Drupal 10 to 11); Drupal 10 itself reaches end of life on 2026-12-09.

A DDEV configuration that runs the examples on this page locally, including Node.js for the Canvas CLI:

Source: Drupal Canvas documentation

Canvas does not replace Drupal’s content model; it adds a layer on top of it.

The component tree is stored as data, not as HTML. Drupal renders it at request time (coupled) or hands it to another application as structured data (headless), so one tree can feed several channels.

An editor with the right permissions sees an Edit link on a Canvas page (and on entities that have a content template). Choosing it opens the editor in the page itself. The exact layout changes between minor releases (1.12 revised the page-editing navigation and added a close button for the right panel), so this section describes the concepts rather than pixel positions.

Enabling the canvas_ai submodule adds an assistant (the sparkle icon) to the editor. It needs the AI module and a provider that supports function calling; configure the provider for all Chat operation types at /admin/config/ai/settings (see AI module and providers).

How it works: an orchestrator reads the prompt and routes it to an agent.

Tips from the documentation: start a prompt with a phrase such as "Using the page builder tool" to force reuse of an existing SDC; use "top", "bottom", "above" and "below" to position content; select a parent and say "into" or "inside" to nest; break a large request into several focused prompts. Describe each component, props and slots in the component guidance form (stored in canvas_ai.component_description.settings, so it can be exported), because there are no built-in slot restrictions.

Known issues: results are non-deterministic, the model can invent an enum value or component ID, and vague prompts give wrong results. Costs: context can exceed 30,000 tokens when many components are enabled, so disable unused components and shorten descriptions under the Canvas AI component description settings. Canvas 1.10 added an Agents & Tools settings form and 1.11 added a Tools dropdown. API keys for the provider belong in the Key module backed by environment variables, never in exported configuration. Review everything the assistant generates before publishing, and remember that generated code components run in visitors' browsers.

Source: Canvas: AI assistant

Coupled is the default: Drupal stores the component tree and renders it with the active theme. SDCs render through Twig, and code components render with Preact on the server and hydrate in the browser. The editor previews the same HTML that visitors receive.

Headless keeps Drupal as the editing and content back end but renders the site in a separate application. The Headless SDK and framework adapters are published as @drupal-canvas/headless (framework-agnostic) and @drupal-canvas/headless-next, -astro, -nuxt, -tanstack-start and -angular. On the Drupal side enable the canvas_headless submodule; it installs Simple OAuth (6.1.0 or later), Consumers and Custom Elements, and adds two restricted permissions, "Administer Canvas Headless frontends" and "Access Canvas Headless preview". The SDK exposes fetchPage() (route context, document head and the component tree) and fetchEntity() (one entity in a content template view mode), plus a component metadata endpoint that publishes the app’s components so editors can place them.

Then, in the Canvas editor, open Headless frontends in the icon rail, choose Add frontend and enter the dev server URL without trailing slash, query or fragment. A row shows Ready, Setup needed or Unreachable, and Canvas previews through the first app in the list. The app holds no client secret; the preview uses single-use assertions signed by the Simple OAuth key pair and a read-only preview scope, which is why unpublished content can appear in the editor’s frame. Prerequisites are Node.js 22.19+ or 24.5+ (Node 23 is not supported), a Chromium-based browser for local HTTP development (Firefox needs HTTPS and Safari needs CHIPS support), and a Simple OAuth keypair configured at /admin/config/people/simple_oauth. Note that getPageData() and getSiteData() throw in headless front ends.

Source: Canvas: Headless setup

Use coupled Canvas when editors need the closest preview and the team already themes in Drupal. Use headless when the site must be rendered by an existing JavaScript application, or when several channels share components; the museum’s gallery kiosk (see Decoupled Drupal with Next.js) can keep using JSON:API alone, and adopt Canvas Headless only if editors need to compose its pages visually. CORS, caching and CDN configuration for a decoupled front end are described in CORS and in the Next.js section of this site (Next.js). Related: GraphQL and JSON:API for data-only access.

Canvas supports symmetric translation: every language shares the same component tree and only the translatable inputs of each component differ. The steps are: enable Language, Content Translation (for Canvas pages) and Configuration Translation (for templates and regions), add languages at /admin/config/regional/language, mark the Page entity and its Components field as translatable at /admin/config/regional/content-language, and install a translation interface. Core’s Content Translation cannot translate a component tree by itself, so use Translation Management Tool (TMGMT) with its Content Entity Source and Config Entity Source plugins, or the experimental Canvas Translate project, which adds translation inside the editor. Translation support has been available without a feature flag since 1.8, and the editor has a language switcher with a tick for translated languages. See also Multilingual Drupal.

Source: Canvas: Translations

Canvas stores its component library, code components, content templates, patterns and component guidance as configuration, and Canvas pages as content. Export configuration after every change to the library and import it on the next environment (see Configuration management and Deployment and CI/CD). Typical pipeline for a code component: develop and test in Workbench, commit the source, run npx canvas push against a development site, export configuration there, review the diff and deploy it with drush deploy. Pushing straight to production bypasses review and should be avoided. After a Canvas update run drush updatedb, drush config:export and drush canvas:doctor; component trees are validated more strictly in 1.11 (parent cycles rejected, lowercase UUIDs required, invalid slot placement no longer fatal), which can surface old data issues.

There is no automatic migration. Drupal CMS 2.0 shipped without a tool that converts Layout Builder sections or Paragraphs into Canvas component trees, so a site that adopts Canvas should plan content migration itself (see Migrate API) or run both side by side: Layout Builder stays in core and Canvas pages and content templates can coexist on different content types. This is worth re-checking against the Drupal CMS and Canvas release notes before a project starts, as the roadmap may add one. Compare options in Layout Builder and in the Paragraphs row of Field types and entity references.

None of the five reference books covers Canvas. Drupal 10 Masterclass (2023) treats Layout Builder as the only visual builder in core and presents later initiatives as future work; since 2025 Drupal CMS ships Canvas, and Layout Builder remains available but is no longer the only choice. Modernizing Drupal 10 Theme Development (2023) describes Single Directory Components as an experimental module with sdc/... library names; SDC has been part of core since 10.3 and is the component format Canvas consumes. Drupal 10 Development Cookbook (2023) covers Layout Builder only and its Drupal 10 baseline is end of life on 2026-12-09, while Canvas needs Drupal 11.3 or later. For Canvas the online documentation and release notes are the only sources.