pixijs-scene-dom-container

This skill covers DOMContainer in PixiJS v8, the mechanism for overlaying HTML elements on the PixiJS canvas and driving their CSS transforms from the scene graph. It is used for native inputs, iframes, videos, or rich HTML that needs to follow a display object's position. DOMContainer is marked EXPERIMENTAL in v8, meaning its API may change between minor releases. It extends ViewContainer and is therefore a leaf in the scene graph: PixiJS children cannot be nested inside it, though HTML content can be nested inside the element itself, and multiple DOMContainer instances can be wrapped in a plain Container. It is unavailable in Web Workers, which have no DOM.

The default pixi.js browser bundle registers the required DOMPipe automatically via browserAll.ts, so DOMContainer works out of the box in a typical browser app. An explicit side-effect import 'pixi.js/dom' (or the combined import that also re-exports the class) is needed only for custom builds using skipExtensionImports: true or non-browser bundles. The constructor accepts all Container options plus two leaf-specific ones: element (any HTMLElement; a bare div is created if omitted) and anchor (a PointData or number controlling the element's origin, where 0 is top-left, 0.5 centers, and 1 is bottom-right). Transforms on the container, including scale, rotation, and inherited alpha, propagate to the element as CSS transform and opacity each frame.

Key behaviors include direct CSS styling of the element (PixiJS does not interfere), pointer-events handling where the shared root div is pointer-events: none and each attached element defaults to auto, and visibility/cleanup semantics where setting visible = false or removing from the scene graph detaches the element, and destroy() removes it while preserving the HTML element for reuse. The DOMPipe uses a shared root div at z-index 1000, exposed as app.domContainerRoot, that hosts every attached element above canvas content and stays aligned via a ResizeObserver on the canvas bounding rect. A documented limitation is that tint, filters, masks, and blendMode are accepted but have no visual effect, since DOM elements live outside the WebGL/WebGPU pipeline; CSS filters and mix-blend-mode must be used instead.