Drupal Canvas

https://project.pages.drupalcode.org/canvas
Admin
Drupal Canvas is a framework for building modern web applications using standard React and...
Tokens:42,446
Snippets:397
Trust Score:9.8
Update:6 days ago
Show doc for...
Tokens:
Raw
### Start the frontend dev server

Source: https://project.pages.drupalcode.org/canvas/headless/setup

Change into the project directory and start the dev server. The dev server prints its local URL: http://localhost:3000 for Next.js, Nuxt, and TanStack Start templates, http://localhost:4321 for Astro.

```bash
cd my-canvas-frontend
npm run dev
```

--------------------------------

### Install Workbench

Source: https://project.pages.drupalcode.org/canvas/code-components/workbench

Install Workbench as a dependency in your project.

```bash
npm install @drupal-canvas/workbench
```

--------------------------------

### Default value with examples property

Source: https://project.pages.drupalcode.org/canvas/sdc-components/validations

Sets default values using the `examples` property. Only the first example is used as the default; additional examples show possible usage. `examples` must be an array, and it is mandatory when the prop is required. Defaults apply when the component is first added to the page.

```yaml
props:
  type: object
  text:
    type: string
    examples:
      - "Hot"
      - "New"
    description: "The text displayed in the badge."

```

--------------------------------

### Custom mobile and desktop viewports example

Source: https://project.pages.drupalcode.org/canvas/apis/theme-settings

Example configuration for a theme that uses a custom mobile breakpoint of 375px and a desktop breakpoint of 1440px. Only the overridden viewports need to be specified.

```yaml
viewports:
  mobile: 375
  desktop: 1440
```

--------------------------------

### Run Workbench after installation

Source: https://project.pages.drupalcode.org/canvas/code-components/workbench

Run Workbench from your project root after installation.

```bash
npx canvas-workbench
```

--------------------------------

### Scaffold TanStack Start frontend with @drupal-canvas/create

Source: https://project.pages.drupalcode.org/canvas/headless/setup

Run this command to scaffold a TanStack Start frontend. The template wires the adapter with canvas() in the plugins array of vite.config.ts.

```bash
npx @drupal-canvas/create@latest my-canvas-frontend \
  --template tanstack-start \
  --site-url https://your-site.example.com \
  --agents none
```

--------------------------------

### Install third-party package date-fns

Source: https://project.pages.drupalcode.org/canvas/code-components/imports-and-assets

Use a local codebase to add packages that are not built in. Install the package with your package manager.

```bash
npm install date-fns

```

--------------------------------

### pages/home.json page preview example

Source: https://project.pages.drupalcode.org/canvas/code-components/workbench/pages

Example page file for pages/home.json. Each element must include a type that matches a discovered component name (e.g., card or js.card); props and slots reference other element IDs in the same elements object. Workbench normalizes this format into a @json-render/react-compatible spec with a synthetic canvas:component-tree wrapper before rendering.

```json
{
  "title": "Home",
  "elements": {
    "header": {
      "type": "js.header",
      "props": {
        "darkVariant": true,
        "backgroundColor": "crust"
      },
      "slots": {
        "branding": ["header-logo"],
        "navigation": ["header-navigation"]
      }
    },
    "header-logo": {
      "type": "js.logo",
      "props": {
        "linkToFrontPage": true
      }
    },
    "header-navigation": {
      "type": "js.navigation",
      "props": {}
    },
    "card-grid": {
      "type": "grid",
      "props": {
        "columns": 3,
        "gap": "md"
      },
      "slots": {
        "items": ["card-1", "card-2", "card-3"]
      }
    },
    "card-1": {
      "type": "card",
      "props": {
        "featured": true
      },
      "slots": {
        "header": ["card-1-header"],
        "content": ["card-1-content"],
        "footer": ["card-1-footer"]
      }
    },
    "card-1-header": {
      "type": "heading",
      "props": {
        "text": "Featured article"
      }
    },
    "card-1-content": {
      "type": "text",
      "props": {
        "content": "Learn how editorial teams use Canvas to review, refine, and publish AI-assisted content."
      }
    },
    "card-1-footer": {
      "type": "button-group",
      "slots": {
        "items": ["card-1-primary-action", "card-1-secondary-action"]
      }
    },
    "card-1-primary-action": {
      "type": "button",
      "props": {
        "label": "Read more",
        "href": "/articles/canvas-workflows"
      }
    },
    "card-1-secondary-action": {
      "type": "button",
      "props": {
        "label": "Save for later",
        "href": "/saved"
      }
    },
    "card-2": {
      "type": "card",
      "props": {
        "featured": false
      },
      "slots": {
        "header": ["card-2-header"],
        "content": ["card-2-content"],
        "footer": ["card-2-footer"]
      }
    },
    "card-2-header": {
      "type": "heading",
      "props": {
        "text": "Documentation update"
      }
    },
    "card-2-content": {
      "type": "text",
      "props": {
        "content": "Review the latest guidance for authoring Workbench component mocks."
      }
    },
    "card-2-footer": {
      "type": "button",
      "props": {
        "label": "Open docs",
        "href": "/docs/workbench-mocks"
      }
    },
    "card-3": {
      "type": "card",
      "props": {
        "featured": false
      },
      "slots": {
        "header": ["card-3-header"],
        "content": ["card-3-content"],
        "footer": ["card-3-footer"]
      }
    },
    "card-3-header": {
      "type": "heading",
      "props": {
        "text": "Team workflow"
      }
    },
    "card-3-content": {
      "type": "text",
      "props": {
        "content": "Coordinate AI drafting, editorial review, and publishing approvals in one place."
      }
    },
    "card-3-footer": {
      "type": "button",
      "props": {
        "label": "See workflow",
        "href": "/workflow"
      }
    }
  }
}
```

--------------------------------

### Language switcher filtering example

Source: https://project.pages.drupalcode.org/canvas/headless/multilingual-sites

Example code showing how to filter translations to available-only entries and build language switcher links using fetchPage() response.

```APIDOC
## Language switcher filtering example

### Description
Demonstrates how to filter route.translations to available-only entries and map them to public URLs for a language switcher.

### Method
fetchPage()

### Endpoint
fetchPage(path)

### Parameters
#### Path Parameters
- **path** (string) - Required - The frontend path to fetch, e.g., "/fr/page/1".

### Request Example
javascript
const page = await fetchPage("/fr/page/1");
if (page && !("redirect" in page)) {
  const languageLinks = page.route.translations
    .filter((translation) => translation.translationAvailable)
    .map((translation) => ({
      label: translation.nativeName, // Or translation.name for localized names.
      active: translation.current,
      rendered: translation.langcode === page.route.entity?.langcode,
      href: toPublicUrl(translation.langcode, translation.url),
    }));
}


### Notes
- `toPublicUrl` is application-owned mapping logic, not an SDK helper.
- Use the original non-external Drupal URI when calling `fetchPage` for a translation.
- `external: true` entries are not valid `fetchPage` input and should be mapped to public URLs.
```

--------------------------------

### Install TMGMT module

Source: https://project.pages.drupalcode.org/canvas/guides/translations

Composer command to download the TMGMT module version ^1.18, required for translating Canvas content.

```bash
composer require 'drupal/tmgmt:^1.18'
```

--------------------------------

### Configure canvas.config.json with custom paths

Source: https://project.pages.drupalcode.org/canvas/code-components/local-codebase

Example canvas.config.json showing all available options. Use this file in the project root when your local codebase does not use the default Canvas paths; you can set only the options you need.

```json
{
  "componentDir": "src/code-components",
  "pagesDir": "pages",
  "contentTemplatesDir": "content-templates",
  "regionsDir": "regions",
  "layoutPath": "src/layout.jsx",
  "aliasBaseDir": "src",
  "outputDir": "dist",
  "globalCssPath": "src/global.css",
  "sync": {
    "pages": true,
    "contentTemplates": true,
    "regions": true
  }
}
```

--------------------------------

### SWR data fetching example

Source: https://project.pages.drupalcode.org/canvas/code-components/data-fetching

Imports useSWR from 'swr' and fetches user data from an API endpoint. Handles loading and error states, displaying 'loading...' and 'failed to load' respectively.

```jsx
import useSWR from 'swr';


export default function Profile() {
  const { data, error, isLoading } = useSWR(
    'https://my-site.com/api/user',
    fetcher,
  );


  if (error) return <div>failed to load</div>;
  if (isLoading) return <div>loading...</div>;
  return <div>hello {data.name}!</div>;
}

```

--------------------------------

### Props format example: heading.mocks.json

Source: https://project.pages.drupalcode.org/canvas/code-components/workbench/mocks

A mock entry using the props format. The name becomes the preview tab label, and props provides prop values for the component.

```json
[
  {
    "name": "Centered",
    "props": {
      "text": "Publish AI-assisted content with editorial control",
      "eyebrow": "Build faster",
      "textAlign": "center"
    }
  }
]
```

--------------------------------

### Example content template: node.article.full.json

Source: https://project.pages.drupalcode.org/canvas/code-components/workbench/content-templates

A complete JSON content template for an article in full view mode, demonstrating entity-field and host-entity-url prop sources, slots, and rich text formatting.

```json
{
  "label": "Article full",
  "entityType": "node",
  "bundle": "article",
  "viewMode": "full",
  "elements": {
    "article-hero": {
      "type": "hero",
      "props": {
        "heading": {
          "sourceType": "entity-field",
          "expression": "ℹ︎␜entity:node:article␝title␞␟value"
        },
        "linkUrl": {
          "sourceType": "host-entity-url",
          "absolute": false
        }
      },
      "slots": {
        "content": ["article-summary"]
      }
    },
    "article-summary": {
      "type": "text",
      "props": {
        "content": {
          "sourceType": "entity-field",
          "expression": "ℹ︎␜entity:node:article␝body␞␟summary"
        }
      }
    },
    "article-cta": {
      "type": "button",
      "props": {
        "label": "Read article",
        "description": {
          "value": "Read the <em>full article</em>.",
          "format": "canvas_html_inline"
        },
        "href": {
          "sourceType": "host-entity-url",
          "absolute": false
        }
      }
    }
  }
}

```

--------------------------------

### Example layout file: src/layout.jsx

Source: https://project.pages.drupalcode.org/canvas/code-components/workbench/regions

Layout component that wraps page and content template previews. Must have a default export accepting children and use the Region component from drupal-canvas to slot in regions by machine name.

```jsx
import { Region } from 'drupal-canvas';


export default function Layout({ children }) {
  return (
    <>
      <Region name="header" />
      <main>{children}</main>
      <Region name="footer" />
    </>
  );
}

```

--------------------------------

### Install Canvas Translate module (experimental)

Source: https://project.pages.drupalcode.org/canvas/guides/translations

Composer command to download the experimental Canvas Translate module version ^1.0@alpha, which provides a translation UI inside the Canvas editor without requiring TMGMT.

```bash
composer require 'drupal/canvas_translate:^1.0@alpha'
```

--------------------------------

### Hello component with firstName prop

Source: https://project.pages.drupalcode.org/canvas/code-components/concepts

Example Code Component that receives a firstName prop and renders a greeting. The prop is automatically converted to camelCase when passed as a parameter.

```jsx
const Hello = ({ firstName }) => {
  return <div className="text-3xl">Hello, {firstName}!</div>;
};


export default Hello;

```

--------------------------------

### Text prop schema

Source: https://project.pages.drupalcode.org/canvas/code-components/component-metadata

Defines a basic text input prop stored as a string. The example shows a default value of 'Hello, world!'.

```yaml
type: string
examples:
  - Hello, world!

```

--------------------------------

### Example region file: regions/header.json

Source: https://project.pages.drupalcode.org/canvas/code-components/workbench/regions

Defines a global region with a status flag and an elements tree. Each element must have a type matching a discovered component name, and can include props and slots referencing other element IDs.

```json
{
  "status": true,
  "elements": {
    "header": {
      "type": "js.header",
      "props": {
        "darkVariant": true,
        "backgroundColor": "crust"
      },
      "slots": {
        "branding": ["header-logo"],
        "navigation": ["header-navigation"]
      }
    },
    "header-logo": {
      "type": "js.logo",
      "props": {
        "linkToFrontPage": true
      }
    },
    "header-navigation": {
      "type": "js.navigation",
      "props": {}
    }
  }
}

```

--------------------------------

### Define custom viewports in {theme}.canvas.yml

Source: https://project.pages.drupalcode.org/canvas/apis/theme-settings

Create a {theme}.canvas.yml file in the theme's root directory to define custom viewport sizes. The example sets mobile, tablet, desktop, and large_desktop widths. If a viewport is missing or invalid, Canvas falls back to the default width for that viewport.

```yaml
viewports:
  mobile: 468
  tablet: 1024
  desktop: 1920
  large_desktop: 2560
```

--------------------------------

### Props and slots format example: card.mocks.json

Source: https://project.pages.drupalcode.org/canvas/code-components/workbench/mocks

A mock entry using the props and slots format. It defines props for the root component, maps slots to element IDs, and defines child elements with types matching discovered component names.

```json
[
  {
    "name": "Featured",
    "props": {
      "featured": true
    },
    "slots": {
      "header": ["card-featured-header"],
      "content": ["card-featured-content"],
      "footer": ["card-featured-actions"]
    },
    "elements": {
      "card-featured-header": {
        "type": "heading",
        "props": {
          "text": "Featured article"
        }
      },
      "card-featured-content": {
        "type": "text",
        "props": {
          "content": "Learn how editorial teams use Canvas to review, refine, and publish AI-assisted content."
        }
      },
      "card-featured-actions": {
        "type": "button-group",
        "props": {
          "stacked": false
        },
        "slots": {
          "items": ["card-featured-primary-action", "card-featured-secondary-action"]
        }
      },
      "card-featured-primary-action": {
        "type": "button",
        "props": {
          "label": "Get started",
          "href": "/sign-up",
          "variant": "primary"
        }
      },
      "card-featured-secondary-action": {
        "type": "button",
        "props": {
          "label": "Read more",
          "href": "/articles/canvas-workflows"
        }
      }
    }
  },
]
```

--------------------------------

### Import and use third-party package date-fns

Source: https://project.pages.drupalcode.org/canvas/code-components/imports-and-assets

After installing date-fns, import it with a standard package import and push the component with the Canvas CLI. When you run `npx canvas push`, the CLI builds the dependency with the component. The import continues to work when the pushed component is edited in the in-browser code editor. Use packages that can run in the browser.

```javascript
import { format } from 'date-fns';


export default function EventDate({ date }) {
  return <time>{format(new Date(date), 'PPP')}</time>;
}

```

--------------------------------

### Scaffold a new component with canvas scaffold

Source: https://project.pages.drupalcode.org/canvas/headless/setup

Run from the project root to generate a new component directory. The directory location depends on componentDir in canvas.config.json (components for Next.js, src/components for Astro and TanStack Start, app/components for Nuxt).

```bash
npx canvas scaffold --name my-hero
```

--------------------------------

### YAML slot descriptions for Card component

Source: https://project.pages.drupalcode.org/canvas/ai-assistant

Example YAML configuration defining slot descriptions for a Card component, specifying that the content slot accepts description text and the actions slot accepts buttons or badges.

```yaml
slots:
  content:
    title: Card Description
    description: >
      The description or body text of the card.
      Don't place buttons or badges here, use the actions slot for that.
  actions:
    title: Actions
    description: The actions of the card, use buttons or badge components here.

```

--------------------------------

### Video prop schema

Source: https://project.pages.drupalcode.org/canvas/code-components/component-metadata

Defines a video object prop with metadata like dimensions and file URL. Only the file URL is required; all other metadata is optional. The example shows a video with src and poster.

```yaml
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

```

--------------------------------

### fetchPage route response with translations

Source: https://project.pages.drupalcode.org/canvas/headless/multilingual-sites

Example response from fetchPage for a multilingual route. Shows route.negotiatedLanguage and route.translations with every enabled language; translationAvailable is false for missing or denied translations, and current follows the requested language.

```json
{
  "name": "entity.canvas_page.canonical",
  "requestUri": "/fr/page/1",
  "params": { "canvas_page": "1" },
  "managedByCanvas": true,
  "entity": {
    "entityType": "canvas_page",
    "bundle": "canvas_page",
    "id": "1",
    "uuid": "11111111-1111-4111-8111-111111111111",
    "langcode": "en"
  },
  "negotiatedLanguage": "fr",
  "translations": [
    { "langcode": "en", "name": "English", "nativeName": "English", "url": "/contact", "translationAvailable": true, "current": false, "external": false },
    { "langcode": "fr", "name": "French", "nativeName": "Français", "url": "/fr/page/1", "translationAvailable": false, "current": true, "external": false },
    { "langcode": "es", "name": "Spanish", "nativeName": "Español", "url": "/es/contacto", "translationAvailable": true, "current": false, "external": false }
  ]
}
```

--------------------------------

### Advanced format example: card.mocks.json

Source: https://project.pages.drupalcode.org/canvas/code-components/workbench/mocks

Shows the advanced format for a card component mock. The 'root' is 'card-grid' and 'elements' defines the full tree including nested cards, headers, content, and footers. Each element type must match a discovered component name like 'card' or 'js.card'.

```json
[
  {
    "name": "In grid",
    "root": "card-grid",
    "elements": {
      "card-grid": {
        "type": "grid",
        "props": {
          "columns": 3,
          "gap": "md"
        },
        "slots": {
          "items": ["card-1", "card-2", "card-3"]
        }
      },
      "card-1": {
        "type": "card",
        "props": {
          "featured": true
        },
        "slots": {
          "header": ["card-1-header"],
          "content": ["card-1-content"],
          "footer": ["card-1-footer"]
        }
      },
      "card-1-header": {
        "type": "heading",
        "props": {
          "text": "Featured article"
        }
      },
      "card-1-content": {
        "type": "text",
        "props": {
          "content": "Learn how editorial teams use Canvas to review, refine, and publish AI-assisted content."
        }
      },
      "card-1-footer": {
        "type": "button-group",
        "slots": {
          "items": ["card-1-primary-action", "card-1-secondary-action"]
        }
      },
      "card-1-primary-action": {
        "type": "button",
        "props": {
          "label": "Read more",
          "href": "/articles/canvas-workflows"
        }
      },
      "card-1-secondary-action": {
        "type": "button",
        "props": {
          "label": "Save for later",
          "href": "/saved"
        }
      },
      "card-2": {
        "type": "card",
        "props": {
          "featured": false
        },
        "slots": {
          "header": ["card-2-header"],
          "content": ["card-2-content"],
          "footer": ["card-2-footer"]
        }
      },
      "card-2-header": {
        "type": "heading",
        "props": {
          "text": "Documentation update"
        }
      },
      "card-2-content": {
        "type": "text",
        "props": {
          "content": "Review the latest guidance for authoring Workbench component mocks."
        }
      },
      "card-2-footer": {
        "type": "button",
        "props": {
          "label": "Open docs",
          "href": "/docs/workbench-mocks"
        }
      },
      "card-3": {
        "type": "card",
        "props": {
          "featured": false
        },
        "slots": {
          "header": ["card-3-header"],
          "content": ["card-3-content"],
          "footer": ["card-3-footer"]
        }
      },
      "card-3-header": {
        "type": "heading",
        "props": {
          "text": "Team workflow"
        }
      },
      "card-3-content": {
        "type": "text",
        "props": {
          "content": "Coordinate AI drafting, editorial review, and publishing approvals in one place."
        }
      },
      "card-3-footer": {
        "type": "button",
        "props": {
          "label": "See workflow",
          "href": "/workflow"
        }
      }
    }
  }
]
```

--------------------------------

### Portable component using useJsonApiClient and SWR

Source: https://project.pages.drupalcode.org/canvas/code-components/data-fetching

Use this component to fetch a collection of articles via JSON:API in a portable way. It uses useJsonApiClient to get the client and useSWR with a stable key. The hook returns null when no client is provided, so pass null as the SWR key in that case. Render data whenever available, including prefetched fallback data.

```jsx
import { useJsonApiClient } from 'drupal-canvas/react';
import useSWR from 'swr';


export default function List() {
  const client = useJsonApiClient();
  const { data, error } = useSWR(client ? 'articles' : null, () =>
    client.getCollection('node--article'),
  );


  if (error) return 'An error has occurred.';
  if (!data) return 'Loading...';
  return (
    <ul>
      {data.map((article) => (
        <li key={article.id}>{article.title}</li>
      ))}
    </ul>
  );
}
```

--------------------------------

### Image prop schema

Source: https://project.pages.drupalcode.org/canvas/code-components/component-metadata

Defines an image object prop with metadata like alt text, dimensions, and file URL. Only the file URL is required; all other metadata is optional. The example shows an image with src, alt, width, and height.

```yaml
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

```

--------------------------------

### preview-build for component target

Source: https://project.pages.drupalcode.org/canvas/code-components/workbench/preview-build

Exports preview artifacts for a component. The `--component-path` must point to a component metadata file inside the configured `componentDir`. Writes `component-default.html`, `component-mock-01.html`, etc., and `manifest.json`.

```bash
npx canvas-workbench preview-build --component-path components/card/component.yml --out-dir .canvas-preview/card
```

--------------------------------

### Boolean prop schema

Source: https://project.pages.drupalcode.org/canvas/code-components/component-metadata

Defines a true or false value prop. The example shows a default value of false.

```yaml
type: boolean
examples:
  - false

```

--------------------------------

### Run Workbench from project root

Source: https://project.pages.drupalcode.org/canvas/code-components/workbench

Run Workbench from your project root using npx. No configuration is required if your project uses the default Canvas layout.

```bash
npx @drupal-canvas/workbench@latest
```

--------------------------------

### Import SVG as URL

Source: https://project.pages.drupalcode.org/canvas/code-components/imports-and-assets

Use a plain .svg import to get a URL for the asset, similar to other static asset imports.

```jsx
import logoUrl from './logo.svg';


export default function LogoImage() {
  return <img src={logoUrl} alt="Drupal Canvas" />;
}

```

--------------------------------

### Scaffold Angular frontend with @drupal-canvas/create

Source: https://project.pages.drupalcode.org/canvas/headless/setup

Run this command to scaffold an Angular frontend. The template wires the adapter similarly to other frameworks.

```bash
npx @drupal-canvas/create@latest my-canvas-frontend \
  --template angular \
  --site-url https://your-site.example.com \
  --agents none
```

--------------------------------

### Number prop schema

Source: https://project.pages.drupalcode.org/canvas/code-components/component-metadata

Defines a numeric value prop that can include decimal places. The example shows a default value of 3.14.

```yaml
type: number
examples:
  - 3.14

```

--------------------------------

### usePageContext - mainEntity language switcher

Source: https://project.pages.drupalcode.org/canvas/code-components/data-fetching

Example React component using usePageContext to access mainEntity and build a language switcher with translations.

```APIDOC
## usePageContext - mainEntity

### Description
Provides access to the mainEntity object which contains language and translation information for building a language switcher.

### Usage
Import from 'drupal-canvas/react' and call within a React component.

### mainEntity Fields
- **requestedLanguage** (string) - The language code requested via the URL (e.g., `fr`).
- **renderedLanguage** (string) - The language the content actually rendered in; falls back to default translation when requested language has no translation.
- **translations** (array) - List of all enabled site languages, each with:
  - **langcode** (string) - Language code (e.g., `en`, `fr`).
  - **name** (string) - Language name in current display language (e.g., `German`).
  - **nativeName** (string) - Language's own native name (e.g., `Deutsch`).
  - **url** (string) - URL to view the entity in this language, resolved according to site's language negotiation.
  - **translationAvailable** (boolean) - Whether the entity has a translation in this language that the current user may view.
  - **current** (boolean) - Whether this is the requested language, even when content falls back to default translation.

### Example
```jsx
import { usePageContext } from 'drupal-canvas/react';

function LanguageSwitcher() {
  const page = usePageContext();
  const mainEntity = page?.mainEntity;
  if (!mainEntity) {
    return null;
  }
  const { requestedLanguage, renderedLanguage, translations } = mainEntity;

  return (
    <nav>
      {requestedLanguage !== renderedLanguage && (
        <p>Not available in your language; showing {renderedLanguage}.</p>
      )}
      <ul>
        {translations.map(
          ({ langcode, nativeName, url, translationAvailable, current }) => (
            <li key={langcode}>
              {current ? (
                <span lang={langcode} aria-current="true">
                  {nativeName}
                </span>
              ) : (
                <a href={url} lang={langcode} hrefLang={langcode}>
                  {nativeName}
                  {!translationAvailable && ' (not translated)'}
                </a>
              )}
            </li>
          ),
        )}
      </ul>
    </nav>
  );
}

export default LanguageSwitcher;
```
```

--------------------------------

### Scaffold Nuxt frontend with @drupal-canvas/create

Source: https://project.pages.drupalcode.org/canvas/headless/setup

Run this command to scaffold a Nuxt frontend. The template wires the adapter by listing @drupal-canvas/headless-nuxt in the modules array of nuxt.config.ts.

```bash
npx @drupal-canvas/create@latest my-canvas-frontend \
  --template nuxt \
  --site-url https://your-site.example.com \
  --agents none
```

--------------------------------

### Adding a Tailwind CSS plugin

Source: https://project.pages.drupalcode.org/canvas/apis/import-maps

Example of using hook_canvas_importmap_alter to register a Tailwind CSS plugin for use with the @plugin directive in Global CSS.

```APIDOC
## Adding a Tailwind CSS plugin

### Description
Register a Tailwind CSS plugin in the import map so it can be used with the `@plugin` directive in Global CSS.

### Method
hook

### Parameters
- **$import_maps** (array) - Required - Reference to the import map array.

### Request Example
```php
function my_module_canvas_importmap_alter(array &$import_maps): void {
  $module_path = \Drupal::service('extension.path.resolver')
    ->getPath('module', 'my_module');

  // Register a Tailwind CSS plugin.
  $import_maps['imports']['@tailwindcss/forms'] = \base_path() . $module_path . '/js/tailwindcss-forms.js';
}
```

### Usage in Global CSS
```css
@plugin "@tailwindcss/forms";
```

### Response
No return value. The hook modifies the `$import_maps` array by reference.
```

--------------------------------

### Scaffold Astro frontend with @drupal-canvas/create

Source: https://project.pages.drupalcode.org/canvas/headless/setup

Run this command to scaffold an Astro frontend. The template wires the adapter with canvas() in the integrations array of astro.config.mjs, which injects the Canvas routes.

```bash
npx @drupal-canvas/create@latest my-canvas-frontend \
  --template astro \
  --site-url https://your-site.example.com \
  --agents none
```

--------------------------------

### Integer prop schema

Source: https://project.pages.drupalcode.org/canvas/code-components/component-metadata

Defines a whole number value prop without decimal places. The example shows a default value of 42.

```yaml
type: integer
examples:
  - 42

```

--------------------------------

### Add SVGR client types for TypeScript

Source: https://project.pages.drupalcode.org/canvas/code-components/imports-and-assets

Add these reference directives to a Vite environment file to get TypeScript types for SVGR imports.

```typescript
/// <reference types="vite/client" />
/// <reference types="vite-plugin-svgr/client" />

```

--------------------------------

### Link prop schema

Source: https://project.pages.drupalcode.org/canvas/code-components/component-metadata

Defines a URL or URI reference prop. The format can be 'uri' (absolute only) or 'uri-reference' (absolute and relative). The example shows an absolute URL.

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

```

--------------------------------

### Formatted text prop schema

Source: https://project.pages.drupalcode.org/canvas/code-components/component-metadata

Defines a rich text prop with HTML formatting support, displayed in a block context. The example shows an HTML string with formatting.

```yaml
type: string
contentMediaType: text/html
x-formatting-context: block
examples:
  - <p>This is <strong>formatted</strong> text with HTML.</p>

```

--------------------------------

### preview-build for page target

Source: https://project.pages.drupalcode.org/canvas/code-components/workbench/preview-build

Exports preview artifacts for a page. The `--page-path` must point to a page JSON file inside the configured `pagesDir`. Writes `page-default.html` and `manifest.json`.

```bash
npx canvas-workbench preview-build --page-path pages/home.json --out-dir .canvas-preview/home
```

--------------------------------

### File structure for index-style component

Source: https://project.pages.drupalcode.org/canvas/code-components/workbench/mocks

Shows the directory layout when the component metadata is named component.yml and the mock file is mocks.json.

```text
src/components/hero/
  index.tsx
  component.yml
  mocks.json
```

--------------------------------

### Import built-in package clsx

Source: https://project.pages.drupalcode.org/canvas/code-components/imports-and-assets

Built-in packages are already available in the in-browser code editor. In a local codebase, install the package in your project so local builds can resolve it.

```javascript
import { clsx } from 'clsx';

```

--------------------------------

### Scaffold Next.js frontend with @drupal-canvas/create

Source: https://project.pages.drupalcode.org/canvas/headless/setup

Run this command to scaffold a Next.js frontend. The template wires the adapter in next.config.ts with withCanvas() and mounts Canvas routes under app/api/. Use --agents none to skip per-agent rule files.

```bash
npx @drupal-canvas/create@latest my-canvas-frontend \
  --template nextjs \
  --site-url https://your-site.example.com \
  --agents none
```

--------------------------------

### Unauthorized response from Canvas components endpoint

Source: https://project.pages.drupalcode.org/canvas/headless/setup

Example HTTP response when no Bearer token is provided. It includes headers and a JSON error body explaining that a Drupal preview assertion is required.

```http
HTTP/1.1 401 Unauthorized
content-security-policy: frame-ancestors 'self'
cache-control: no-store
content-type: application/json
www-authenticate: Bearer


{"error":"missing_assertion","message":"Provide a Drupal preview assertion as a Bearer token. Assertions are single-use; mint a fresh one per request."}
```

--------------------------------

### Push local Canvas content with npx canvas push

Source: https://project.pages.drupalcode.org/canvas/code-components/local-codebase

Builds and uploads local Canvas content. Discovers components, builds browser assets, runs Tailwind CSS build, uploads component configuration, syncs global CSS, and pushes pages, content templates, and global regions by default. Use --no-pages, --no-content-templates, or --no-regions to exclude them for a single run, or set sync.pages, sync.contentTemplates, or sync.regions to false in canvas.config.json. Brand Kit fonts are included with --include-brand-kit or CANVAS_INCLUDE_BRAND_KIT=true when canvas.brand-kit.json is present.

```bash
npx canvas push
```

--------------------------------

### Jumbotron component with header and buttonFooter slots

Source: https://project.pages.drupalcode.org/canvas/code-components/concepts

Example Code Component that uses slots for header and buttonFooter, allowing other components to be placed inside. Slot names are camelCased when passed as parameters.

```jsx
const Jumbotron = ({ header, buttonFooter }) => {
  return (
    <section>
      <div>{header}</div>
      <div>
        <button>
          <a href="#">CTA Button</a>
        </button>
        {buttonFooter}
      </div>
    </section>
  );
};


export default Jumbotron;

```

--------------------------------

### cn utility for combining Tailwind CSS classes

Source: https://project.pages.drupalcode.org/canvas/code-components/packages

Utility for combining Tailwind CSS classes. The example shows a ControlDots component using cn to merge a default class with a className prop.

```jsx
import { cn } from 'drupal-canvas';


export default function Example() {
  return <ControlDots className="top-4 left-4 stroke-white absolute" />;
}


const ControlDots = ({ className }) => (
  <svg
    xmlns="http://www.w3.org/2000/svg"
    viewBox="0 0 31 9"
    fill="none"
    strokeWidth="2"
    className={cn('w-12', className)}
  >
    <ellipse cx="4.13" cy="4.97" rx="3.13" ry="2.97" />
    <ellipse cx="15.16" cy="4.97" rx="3.13" ry="2.97" />
    <ellipse cx="26.19" cy="4.97" rx="3.13" ry="2.97" />
  </svg>
);
```

--------------------------------

### usePageContext and useSiteContext example

Source: https://project.pages.drupalcode.org/canvas/code-components/data-fetching

Uses usePageContext and useSiteContext hooks from 'drupal-canvas/react' to access page and site data. Returns null if either is unavailable, and renders a header with site branding and page title.

```jsx
import { usePageContext, useSiteContext } from 'drupal-canvas/react';


export default function PageHeader() {
  const page = usePageContext();
  const site = useSiteContext();
  if (!page || !site) return null;
  return (
    <header>
      <a href={site.branding.homeUrl}>{site.branding.siteName}</a>
      <h1>{page.pageTitle}</h1>
    </header>
  );
}

```

--------------------------------

### Scaffold a local codebase with @drupal-canvas/create

Source: https://project.pages.drupalcode.org/canvas/code-components/local-codebase

Run this command to scaffold a new local Canvas codebase. The generated project is generally ready to use with the Canvas CLI, depending on the template.

```bash
npx @drupal-canvas/create@latest
```

--------------------------------

### Unsupported: import helper from component directory

Source: https://project.pages.drupalcode.org/canvas/code-components/imports-and-assets

Do not use @/components to import helper files from inside a component directory. Move shared helpers outside.

```javascript
// Do not use this.
import { formatPrice } from '@/components/pricing-card/helpers';

```

--------------------------------

### Create canvas.config.json

Source: https://project.pages.drupalcode.org/canvas/code-components/workbench

Create a canvas.config.json file in your project root to customize Workbench paths. Only set the options you need; defaults are used for unspecified properties.

```json
{
  "componentDir": "src/components",
  "pagesDir": "pages",
  "contentTemplatesDir": "content-templates",
  "regionsDir": "regions",
  "layoutPath": "src/layout.jsx",
  "aliasBaseDir": "src",
  "globalCssPath": "src/global.css"
}
```
Tokens:
Raw