Pixijs Scene Dom Container

DOMContainer positions an HTML element over the PixiJS canvas and drives its CSS transform from the scene graph. Use it for native inputs, iframes, videos, or rich HTML that needs to follow a display object's position. The default pixi.js browser bundle registers the DOMPipe automatically; custom builds add a side-effect import 'pixi.js/dom'.

DOMContainer is marked EXPERIMENTAL in PixiJS v8. The API may change between minor releases.

Assumes familiarity with pixijs-scene-core-concepts. DOMContainer extends ViewContainer, so it's a leaf: do not nest PixiJS children inside it. Nest DOM content inside the HTML element itself, or wrap multiple DOMContainer instances in a Container. Not available in Web Workers; a worker has no DOM to overlay.

Quick Start

import "pixi.js/dom";

const input = document.createElement("input");
input.type = "text";
input.placeholder = "Enter name...";

const dom = new DOMContainer({
  element: input,
  anchor: 0.5,
});
dom.position.set(app.screen.width / 2, app.screen.height / 2);

app.stage.addChild(dom);

Related skills: pixijs-scene-core-concepts (scene graph basics), pixijs-scene-container (wrap multiple DOM overlays), pixijs-events (pointer handling on canvas vs DOM), pixijs-accessibility (screen-reader overlays).

Constructor options

All Container options (position, scale, tint, label, filters, zIndex, etc.) are also valid here — see skills/pixijs-scene-core-concepts/references/constructor-options.md.

Leaf-specific options added by DOMContainerOptions:

tint, filters, mask, and blendMode are accepted (inherited from Container) but have no visual effect — DOM elements live outside the WebGL/WebGPU pipeline. Style the element via CSS for those effects.

Core Patterns

Setup and the side-effect import

import "pixi.js/dom";
import { DOMContainer } from "pixi.js";

Or use the combined import that registers the pipe and re-exports the class:

import { DOMContainer } from "pixi.js/dom";

The default pixi.js browser bundle already imports pixi.js/dom for you via browserAll.ts, so DOMContainer works out of the box in a typical browser app. You only need the explicit import 'pixi.js/dom' line when you set skipExtensionImports: true (custom builds) or when running under a non-browser bundle.

Transforms, anchor, and alpha

const dom = new DOMContainer({
  element: document.createElement("div"),
  anchor: 0.5,
});
dom.position.set(400, 300);
dom.scale.set(1.5);
dom.rotation = Math.PI / 8;
dom.alpha = 0.5;

Transforms on the DOMContainer propagate to the element as CSS transform. anchor shifts the element's origin relative to its own dimensions: 0 is top-left, 0.5 centers, 1 is bottom-right. A single number sets both axes; an object { x, y } sets each independently. alpha (including inherited parent alpha) is written to the element's style.opacity every frame.

If no element is provided, a <div> is created by default.

Styling the element directly

const panel = document.createElement("div");
panel.innerHTML = "<h2>Score</h2><p>1500</p>";
panel.style.color = "white";
panel.style.fontFamily = "Arial";
panel.style.pointerEvents = "none";

const dom = new DOMContainer({ element: panel });
dom.position.set(50, 50);
app.stage.addChild(dom);

PixiJS does not interfere with CSS styling on the element. The shared root <div> is set to pointer-events: none, and each attached element defaults to pointer-events: auto. Override to none on purely decorative overlays so the canvas still receives clicks underneath them.

Visibility and cleanup

dom.visible = false;
dom.visible = true;

dom.destroy();

Setting visible = false or removing the DOMContainer from the scene graph detaches the element from the DOM. Restoring visibility re-attaches it. destroy() removes the element from its parent node and nulls internal references; the HTML element itself is preserved, so you can re-attach it elsewhere:

const element = dom.element;
dom.destroy();
document.body.appendChild(element);