Overview

Available components

Most of the PixiJS display components are available as Solid components in Pixi Solid.

All components are named the same as their PixiJS counterparts and should be imported individually.

This pattern also allows treeshaking when using a bundler that supports it as each component only imports the necessary parts of PixiJS that it needs.

All of the components take the same props as their PixiJS counterparts, with the addition of event handlers.

The best reference for the purpose, capabilities and options for the pixi-solid components is the PixiJS docs themselves.

These include:

import {
  AnimatedSprite,
  BitmapText,
  Container,
  Graphics,
  HTMLText,
  MeshPlane,
  MeshRope,
  NineSliceSprite,
  ParticleContainer,
  PerspectiveMesh,
  RenderContainer,
  RenderLayer,
  Sprite,
  Text,
  TilingSprite,
} from "pixi-solid";

This can cause some name clashes if you are also importing classes or types from pixi.js directly.

It's recommended to alias the imports from pixi.js in these cases, for example:

import { Sprite as PixiSprite } from "pixi.js";
import { Sprite } from "pixi-solid";
//...

Or import all Pixi types under a namespace because these will not be bundled into the final build anyway:

import * as Pixi from "pixi.js";
import { Sprite } from "pixi-solid";

//...

let spriteRef: Pixi.Sprite | undefined;
//...

Point-axis props by component

All components support point-axis shorthand props for fine-grained reactivity. The specific axes available depend on the component type:

Component	Point-axis props
Container, RenderContainer, RenderLayer, Graphics, ParticleContainer	positionX/Y, scaleX/Y, pivotX/Y, skewX/Y
Sprite, Text, BitmapText, HTMLText, NineSliceSprite, MeshPlane, MeshRope, PerspectiveMesh, AnimatedSprite	positionX/Y, scaleX/Y, pivotX/Y, skewX/Y, anchorX/Y
TilingSprite	positionX/Y, scaleX/Y, pivotX/Y, skewX/Y, anchorX/Y, tilePositionX/Y, tileScaleX/Y

Why axis props?

SolidJS tracks changes by reference. Passing position={{ x: 100, y: 200 }} allocates a new object on every update, which both triggers the entire point to rebind and creates GC pressure. Axis props like positionX and positionY are plain number values — no allocations, and only the changed axis triggers an update.

Property names

All standard PixiJS properties available on a display object instance (e.g., x, y, rotation, alpha, width, height, scale, position, pivot, anchor, skew etc.) are directly available as props on the pixi-solid components.

In addition to this, pixi-solid enhances these point-based properties (like position, scale, pivot, anchor, and skew) by providing individual axis props. This means you can control position.x independently using positionX, position.y with positionY, and similarly for scaleX, scaleY, pivotX, pivotY, anchorX, anchorY, skewX, and skewY. This allows for more granular control over these properties directly through JSX props without needing to create a new object for every update.

Accessing the instance with Refs

Just like when using SolidJS with the DOM we can access the rendered object instance with a ref. In our case this is useful for calling methods on the PixiJS objects or interacting directly with PixiJS in an imperative way.

We can use a variable or a callback function to access refs.

Ref as a variable.

import type * as Pixi from "pixi.js";
import { Container, onTick } from "pixi-solid";

export const ExampleComponent = () => {
  // Get a ref to the Container
  let containerRef: Pixi.Container | undefined;

  onTick((ticker) => {
    if (!containerRef) return;
    containerRef.rotation += ticker.deltaTime;
  });

  return <Container ref={containerRef}>{/* ...any children */}</Container>;
};

Ref as a callback.

import type * as Pixi from "pixi.js";
import { Container, onTick } from "pixi-solid";

export const ExampleComponent = () => {
  return (
    <Container
      ref={(instance) => {
        onTick((ticker) => {
          instance.rotation += ticker.deltaTime;
        });
      }}
    >
      {/* ...children */}
    </Container>
  );
};

Using a pre-existing instance with the as prop

All pixi-solid components accept an optional as prop to use a pre-existing PixiJS instance instead of creating a new one. This is useful for sharing a single instance across parts of the tree, providing pre-configured instances, or injecting mock instances in tests.

import { Container, Sprite } from "pixi-solid";
import { Container as PixiContainer } from "pixi.js";

const existingContainer = new PixiContainer();
existingContainer.label = "my-container";

const App = () => (
  <Container as={existingContainer}>
    <Sprite texture={Texture.WHITE} />
  </Container>
);

Lifecycle note

When as is provided, pixi-solid assumes you own the instance's lifecycle and will not destroy it on unmount. You must destroy it manually when it is no longer needed.

import { onCleanup } from "solid-js";

const App = () => {
  const existingContainer = new PixiContainer();

  onCleanup(() => {
    existingContainer.destroy({ children: true });
  });

  return (
    <Container as={existingContainer}>
      <Sprite texture={Texture.WHITE} />
    </Container>
  );
};

Omissions

Some PixiJS classes are deliberately omitted because wrapping them in a SolidJS component doesn't add much value:

• Particle — Particles inside a ParticleContainer are designed for maximum-performance, high-volume imperative updates. A dedicated SolidJS component for individual particles contradicts that goal. Create and manage particle instances imperatively with a <ParticleContainer /> as the parent.
• MeshGeometry, NineSliceGeometry, PerspectivePlaneGeometry, PlaneGeometry, RopeGeometry — These are low-level geometry classes used when building custom meshes. Create them imperatively with PixiJS and wrap in a custom pixi-solid component when needed.
• Culler — May be added in the future; hasn't been evaluated enough to determine if a SolidJS component would be useful.