tessl/npm-pixi--react

React integration for PixiJS enabling declarative 2D graphics programming with JSX and React patterns.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Root Creation

Name: tessl/npm-pixi--react
Author: tessl

The createRoot function provides an imperative API for creating PixiJS React roots, offering more control over application lifecycle and integration with existing applications.

Capabilities

Create Root Function

Creates a new root for a PixiJS React application with programmatic control.

/**
 * Creates a new root for a Pixi React app
 * @param target - The DOM node which will serve as the root for this tree
 * @param options - Options to configure the tree
 * @returns Root instance for rendering PixiJS React components
 */
function createRoot(
  target: HTMLElement | HTMLCanvasElement,
  options?: CreateRootOptions
): Root;

interface CreateRootOptions {
  /** Callback to be fired when the application finishes initializing */
  onInit?: (app: PixiApplication) => void;
}

interface Root {
  /** 
   * Render PixiJS React components to the root
   * @param children - React components to render
   * @param applicationOptions - PixiJS application configuration
   * @returns Promise resolving to the PixiJS Application instance
   */
  render(children: ReactNode, applicationOptions: ApplicationOptions): Promise<PixiApplication>;
}

Usage Examples:

import { createRoot, extend } from "@pixi/react";
import { Container, Graphics } from "pixi.js";
import React from "react";

extend({ Container, Graphics });

// Basic imperative usage
const ImperativeExample = async () => {
  const canvas = document.getElementById("pixi-canvas") as HTMLCanvasElement;
  
  const root = createRoot(canvas, {
    onInit: (app) => {
      console.log("PixiJS app initialized:", app);
    }
  });

  const app = await root.render(
    React.createElement("pixiContainer", { x: 100, y: 100 },
      React.createElement("pixiGraphics", {
        draw: (graphics) => {
          graphics.clear();
          graphics.setFillStyle({ color: "blue" });
          graphics.circle(0, 0, 50);
          graphics.fill();
        }
      })
    ),
    {
      width: 800,
      height: 600,
      backgroundColor: "0x1099bb"
    }
  );

  return app;
};

// Integration with existing DOM structure
const DOMIntegrationExample = () => {
  const initializePixi = async () => {
    const container = document.createElement("div");
    container.style.width = "100%";
    container.style.height = "400px";
    document.body.appendChild(container);

    const root = createRoot(container);
    
    await root.render(
      React.createElement("pixiContainer", {},
        React.createElement("pixiText", {
          text: "Dynamically created!",
          x: 200,
          y: 150,
          style: { fontSize: 24, fill: "white" }
        })
      ),
      { width: 800, height: 400 }
    );
  };

  return { initializePixi };
};

// Multiple roots management
const MultiRootExample = async () => {
  const canvas1 = document.getElementById("canvas-1") as HTMLCanvasElement;
  const canvas2 = document.getElementById("canvas-2") as HTMLCanvasElement;

  const root1 = createRoot(canvas1);
  const root2 = createRoot(canvas2);

  // Render different content to each root
  const [app1, app2] = await Promise.all([
    root1.render(
      React.createElement("pixiText", { text: "First App", x: 100, y: 100 }),
      { width: 400, height: 300, backgroundColor: "red" }
    ),
    root2.render(
      React.createElement("pixiText", { text: "Second App", x: 100, y: 100 }),
      { width: 400, height: 300, backgroundColor: "blue" }
    )
  ]);

  return { app1, app2 };
};

Canvas vs Container Target

The createRoot function accepts both canvas elements and container elements:

// Using existing canvas element
const canvasRoot = createRoot(
  document.getElementById("my-canvas") as HTMLCanvasElement
);

// Using container element (canvas will be created automatically)
const containerRoot = createRoot(
  document.getElementById("my-container") as HTMLDivElement
);

Re-rendering

Roots can be re-rendered with different content or options:

const root = createRoot(document.getElementById("canvas") as HTMLCanvasElement);

// Initial render
await root.render(
  React.createElement("pixiText", { text: "Hello", x: 100, y: 100 }),
  { width: 800, height: 600 }
);

// Re-render with different content
await root.render(
  React.createElement("pixiText", { text: "Updated!", x: 150, y: 150 }),
  { width: 800, height: 600, backgroundColor: "0x333333" }
);

Application Options

All PixiJS ApplicationOptions are supported in the render method:

interface ApplicationOptions {
  /** Canvas width in pixels */
  width?: number;
  /** Canvas height in pixels */
  height?: number;
  /** Background color of the canvas */
  backgroundColor?: ColorSource;
  /** Background alpha transparency */
  backgroundAlpha?: number;
  /** Enable antialiasing for smoother graphics */
  antialias?: boolean;
  /** Device pixel ratio for high-DPI displays */
  resolution?: number;
  /** Automatically adjust resolution based on device pixel ratio */
  autoDensity?: boolean;
  /** WebGL power preference */
  powerPreference?: WebGLPowerPreference;
  /** Enable premultiplied alpha */
  premultipliedAlpha?: boolean;
  /** Preserve drawing buffer for reading pixels */
  preserveDrawingBuffer?: boolean;
  /** Clear canvas before each render */
  clearBeforeRender?: boolean;
  /** Show PixiJS hello message in console */
  hello?: boolean;
}