Building HTML canvases
Some canvases are documents or graphics programs, not applications: a written report, a diagram,
a generative-art piece, a WebGL scene. For these, semantic HTML, CSS, and direct browser APIs are
the right tools — don't force Quill components or React state onto a static page.
The wrapper the current runtime requires
Every canvas keeps src/canvas.tsx as its mounted React entry component (default export, no
props). Keep the React layer as a thin shell and write the
experience in HTML/CSS/browser APIs inside it:
- A document is JSX that is effectively semantic HTML —
<article>, headings, lists, tables,
figures — with a <style> block for typography and layout. Write real, specific copy.
- A drawing/WebGL program renders a
<canvas> element and drives it imperatively from a
useEffect via a ref: get the 2D/WebGL context, run the setup and render loop there.
- Clean up in the effect's return: cancel
requestAnimationFrame loops, remove listeners, and
release contexts, so theme switches and remounts don't leak or double-run.
- Mixing tiers is fine: a mostly static page can mount one interactive island, and a data board
can hand a chart's
<canvas> to imperative code while React owns the chrome.
The import allowlist still applies (react, react-dom, @posthog/quill, recharts, lucide-react,
dayjs) — browser globals (document, CanvasRenderingContext2D, WebGLRenderingContext,
requestAnimationFrame, IntersectionObserver, Web Audio, etc.) need no import. Three.js and
other npm graphics libraries are not yet loadable; write against raw WebGL or 2D canvas until the
build pipeline's dependency admission ships.
Styling and theme without Quill
- Size the outermost JSX/HTML element to the iframe viewport with
h-screen or height: 100vh.
Do not use h-full or height: 100% on that root: a published canvas's artifact shell gives
its html, body, and #root elements no explicit height, so percentage height collapses to
the content height. Descendants may use percentage height after the outermost element establishes
the viewport height.
- Use Tailwind utilities and/or a
<style> block (keyframes and complex selectors are fine).
- The host toggles a
.dark class on the document root when the user's PostHog theme changes.
Define your colors as CSS variables under :root { … } with overrides under html.dark { … },
or use theme token utilities (bg-background, text-foreground, border-border) — never a
light-only hardcoded color.
- For canvas/WebGL drawing colors, read the resolved token at runtime
(
getComputedStyle(document.documentElement).getPropertyValue("--primary")) or your own CSS
variables, and re-read on theme change if the scene is long-lived.
Rules that still apply
- PostHog data comes only through the
ph bridge (see querying-canvas-data), including
ph.capture for interaction analytics. Other requests and external styles, images, fonts, media,
or frames require their exact public HTTPS origins in capabilities.network.origins and work only
after publishing. Remote scripts and dynamic imports remain blocked.
- A document that states PostHog numbers must make each one verifiable: an insight-backed number
links its saved insight through
ph.openExternal (URL from the generate-app-url MCP tool,
from a click); an ad-hoc ph.query number discloses the exact query that ran in a <details>
element beside the claim — see "Verifiability" in querying-canvas-data.
- External links go through
ph.openExternal(url) (posthog.com origins only), from a user
interaction.
- Validate and publish through the canvas tools as described in
validating-and-publishing-canvases.
1---2name: building-html-canvases3description: Author a PostHog canvas with semantic HTML, CSS, and direct browser APIs — documents, articles, generative graphics, 2D canvas and WebGL experiences, and focused experiments where React components add no useful structure. Use after building-canvases has routed a canvas request to a plain-HTML/browser-API implementation. Covers the thin component wrapper the current runtime requires, styling and theming without Quill, drawing surfaces, and animation/cleanup patterns.4---5
6# Building HTML canvases
7
8Some canvases are documents or graphics programs, not applications: a written report, a diagram,
9a generative-art piece, a WebGL scene. For these, semantic HTML, CSS, and direct browser APIs are
10the right tools — don't force Quill components or React state onto a static page.
11
12## The wrapper the current runtime requires
13
14Every canvas keeps `src/canvas.tsx` as its mounted React entry component (default export, no
15props). Keep the React layer as a thin shell and write the
16experience in HTML/CSS/browser APIs inside it:
17
18- A document is JSX that is effectively semantic HTML — `<article>`, headings, lists, tables,
19 figures — with a `<style>` block for typography and layout. Write real, specific copy.
20- A drawing/WebGL program renders a `<canvas>` element and drives it imperatively from a
21 `useEffect` via a ref: get the 2D/WebGL context, run the setup and render loop there.
22- Clean up in the effect's return: cancel `requestAnimationFrame` loops, remove listeners, and
23 release contexts, so theme switches and remounts don't leak or double-run.
24- Mixing tiers is fine: a mostly static page can mount one interactive island, and a data board
25 can hand a chart's `<canvas>` to imperative code while React owns the chrome.
26
27The import allowlist still applies (react, react-dom, @posthog/quill, recharts, lucide-react,
28dayjs) — browser globals (`document`, `CanvasRenderingContext2D`, `WebGLRenderingContext`,
29`requestAnimationFrame`, `IntersectionObserver`, Web Audio, etc.) need no import. Three.js and
30other npm graphics libraries are not yet loadable; write against raw WebGL or 2D canvas until the
31build pipeline's dependency admission ships.
32
33## Styling and theme without Quill
34
35- Size the outermost JSX/HTML element to the iframe viewport with `h-screen` or `height: 100vh`.
36 Do not use `h-full` or `height: 100%` on that root: a published canvas's artifact shell gives
37 its `html`, `body`, and `#root` elements no explicit height, so percentage height collapses to
38 the content height. Descendants may use percentage height after the outermost element establishes
39 the viewport height.
40- Use Tailwind utilities and/or a `<style>` block (keyframes and complex selectors are fine).
41- The host toggles a `.dark` class on the document root when the user's PostHog theme changes.
42 Define your colors as CSS variables under `:root { … }` with overrides under `html.dark { … }`,
43 or use theme token utilities (`bg-background`, `text-foreground`, `border-border`) — never a
44 light-only hardcoded color.
45- For canvas/WebGL drawing colors, read the resolved token at runtime
46 (`getComputedStyle(document.documentElement).getPropertyValue("--primary")`) or your own CSS
47 variables, and re-read on theme change if the scene is long-lived.
48
49## Rules that still apply
50
51- PostHog data comes only through the `ph` bridge (see `querying-canvas-data`), including
52 `ph.capture` for interaction analytics. Other requests and external styles, images, fonts, media,
53 or frames require their exact public HTTPS origins in `capabilities.network.origins` and work only
54 after publishing. Remote scripts and dynamic imports remain blocked.
55- A document that states PostHog numbers must make each one verifiable: an insight-backed number
56 links its saved insight through `ph.openExternal` (URL from the `generate-app-url` MCP tool,
57 from a click); an ad-hoc `ph.query` number discloses the exact query that ran in a `<details>`
58 element beside the claim — see "Verifiability" in `querying-canvas-data`.
59- External links go through `ph.openExternal(url)` (posthog.com origins only), from a user
60 interaction.
61- Validate and publish through the canvas tools as described in `validating-and-publishing-canvases`.
posthog