$npx -y skills add pixijs/pixijs-skills --skill pixijs-html-sourceUse this skill when rendering live HTML/DOM elements (or frozen snapshots of them) as PixiJS v8 textures via the EXPERIMENTAL HTML-in-Canvas browser APIs. Covers the pixi.js/html-source side-effect import, feature-detection with canvas.requestPaint, HTMLSource for a live, repaint
| 1 | `HTMLSource` and `ElementImageSource` turn a DOM element into a `TextureSource` you can use anywhere a normal texture works: on a `Sprite`, as a `Texture` frame, or mapped onto a `Mesh`. `HTMLSource` mirrors a live element's pixels into the GPU (the element stays editable and clickable in the browser); `ElementImageSource` wraps an immutable snapshot that never repaints. Both require a side-effect `import 'pixi.js/html-source'` to register their extensions. |
| 2 | |
| 3 | > These sources rely on the experimental HTML-in-Canvas browser proposal and are marked EXPERIMENTAL in PixiJS v8. The browser API must be enabled or the texture uploader throws on first render; feature-detect with `canvas.requestPaint` before relying on it. The API may change between minor releases. |
| 4 | |
| 5 | Assumes familiarity with `pixijs-scene-sprite` and textures. These are texture *sources*, not display objects: wrap them in a `Sprite` (or `Texture`/`Mesh`) to put them on screen. Not available in Web Workers; a worker has no DOM to capture. |
| 6 | |
| 7 | ## Quick Start |
| 8 | |
| 9 | ```ts |
| 10 | import "pixi.js/html-source"; |
| 11 | import { Application, Sprite } from "pixi.js"; |
| 12 | import { HTMLSource } from "pixi.js/html-source"; |
| 13 | |
| 14 | const app = new Application(); |
| 15 | await app.init({ resizeTo: window }); |
| 16 | document.body.appendChild(app.canvas); |
| 17 | |
| 18 | // The element must be a direct child of the Pixi canvas. |
| 19 | const form = document.createElement("form"); |
| 20 | form.innerHTML = '<input value="still editable" />'; |
| 21 | app.canvas.appendChild(form); |
| 22 | |
| 23 | // Render the live form as a sprite. It stays interactive in the browser. |
| 24 | const source = new HTMLSource({ resource: form }); |
| 25 | const sprite = Sprite.from(source); |
| 26 | |
| 27 | sprite.anchor.set(0.5); |
| 28 | sprite.position.set(app.screen.width / 2, app.screen.height / 2); |
| 29 | app.stage.addChild(sprite); |
| 30 | ``` |
| 31 | |
| 32 | **Related skills:** `pixijs-scene-sprite` (display the texture), `pixijs-scene-mesh` (map onto geometry, `PerspectiveMesh`), `pixijs-scene-dom-container` (the opposite: overlay HTML *above* the canvas, outside the GPU pipeline), `pixijs-assets` (texture sources vs the loader/cache), `pixijs-environments` (no DOM in Web Workers). |
| 33 | |
| 34 | ## Constructor options |
| 35 | |
| 36 | Both sources extend `TextureSource`, so all `TextureSourceOptions` (`resolution`, `scaleMode`, `addressMode`, `label`, etc.) are valid. `resource` is required on each. |
| 37 | |
| 38 | `HTMLSourceOptions` (live element): |
| 39 | |
| 40 | | Option | Type | Default | Description | |
| 41 | | ------------------ | ------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | |
| 42 | | `resource` | `Element` | — | Required. The live DOM element to render. Must be a direct child of the owning canvas, or the constructor throws. | |
| 43 | | `canvas` | `HTMLSourceCanvas` | — | The canvas that owns the element's layout subtree. Inferred from `resource.parentElement` when the element is a direct canvas child; pass it when inference is not possible. | |
| 44 | | `autoLayout` | `boolean` | `true` | Set the `layoutsubtree` attribute on the owning canvas. The browser only lays out and paints canvas children when it is present. Set `false` if you write `<canvas layoutsubtree>` yourself. | |
| 45 | | `autoUpdate` | `boolean` | `true` | Listen for the canvas `paint` event and re-upload when the element repaints. Set `false` for a static, captured-once texture. | |
| 46 | | `autoRequestPaint` | `boolean` | `true` | Request one initial paint after construction. Set `false` and call `source.requestPaint()` yourself each frame for continuous animation. | |
| 47 | |
| 48 | `ElementImageSourceOptions` (immutable snapshot): |
| 49 | |
| 50 | | Option | Type | Default | Description |