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

Component Extension

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

The component extension system allows you to register PixiJS classes for use as JSX elements. This selective import approach keeps bundle sizes small and provides type-safe access to PixiJS components.

Capabilities

Extend Function

Registers PixiJS components for JSX usage, enabling selective imports and bundle optimization.

/**
 * Expose Pixi.js components for use in JSX
 * @param objects - Object mapping component names to PixiJS constructor classes
 */
function extend(objects: { [key: string]: new (...args: any) => any }): void;

Usage Examples:

import { extend } from "@pixi/react";
import { 
  Container, 
  Graphics, 
  Text, 
  Sprite, 
  TilingSprite,
  ParticleContainer 
} from "pixi.js";

// Basic component registration
extend({
  Container,
  Graphics,
  Text,
});

// Now you can use these as JSX elements
const BasicScene = () => (
  <pixiContainer x={100} y={100}>
    <pixiGraphics draw={(g) => { /* drawing code */ }} />
    <pixiText text="Hello World!" />
  </pixiContainer>
);

// Advanced component registration
extend({
  Sprite,
  TilingSprite,
  ParticleContainer,
});

const AdvancedScene = () => (
  <pixiContainer>
    <pixiSprite texture={myTexture} x={50} y={50} />
    <pixiTilingSprite 
      texture={tileTexture} 
      width={200} 
      height={200} 
      tileScale={{ x: 0.5, y: 0.5 }}
    />
    <pixiParticleContainer maxSize={1000}>
      {/* particle sprites */}
    </pixiParticleContainer>
  </pixiContainer>
);

Component Naming Convention

Extended components are available as JSX elements with "pixi" prefix:

extend({ Container }); // Available as <pixiContainer>
extend({ Graphics }); // Available as <pixiGraphics>
extend({ Text }); // Available as <pixiText>
extend({ BitmapText }); // Available as <pixiBitmapText>

Special naming overrides for HTML-prefixed components:

extend({ HTMLText }); // Available as <pixiHtmlText> (not <pixiHTMLText>)
extend({ HTMLTextStyle }); // Available as <pixiHtmlTextStyle>

Batch Extension

import * as PIXI from "pixi.js";

// Register common display objects
extend({
  Container: PIXI.Container,
  Graphics: PIXI.Graphics,
  Text: PIXI.Text,
  Sprite: PIXI.Sprite,
  AnimatedSprite: PIXI.AnimatedSprite,
});

// Register mesh components
extend({
  Mesh: PIXI.Mesh,
  PlaneGeometry: PIXI.PlaneGeometry,
  MeshMaterial: PIXI.MeshMaterial,
});

// Register filter components
extend({
  BlurFilter: PIXI.BlurFilter,
  ColorMatrixFilter: PIXI.ColorMatrixFilter,
  DisplacementFilter: PIXI.DisplacementFilter,
});

Custom Component Registration

import { extend } from "@pixi/react";
import { Container } from "pixi.js";

// Custom PixiJS class
class CustomSprite extends Container {
  constructor(options = {}) {
    super();
    // Custom initialization
    this.customProperty = options.customValue;
  }

  customMethod() {
    // Custom functionality
  }
}

// Register custom component
extend({ CustomSprite });

// Use in JSX
const CustomScene = () => (
  <pixiContainer>
    <pixiCustomSprite customValue="test" x={100} y={100} />
  </pixiContainer>
);

Third-Party Plugin Integration

import { extend } from "@pixi/react";
import { Spine } from "pixi-spine";
import { Live2DModel } from "pixi-live2d-display";
import { Viewport } from "pixi-viewport";

// Register plugin components
extend({
  Spine,
  Live2DModel,
  Viewport,
});

const PluginScene = () => (
  <pixiContainer>
    <pixiViewport 
      screenWidth={800} 
      screenHeight={600}
      worldWidth={1200}
      worldHeight={900}
    >
      <pixiSpine 
        spineData={spineData}
        x={400}
        y={300}
      />
      <pixiLive2DModel 
        modelUrl="model.model3.json"
        x={200}
        y={200}
      />
    </pixiViewport>
  </pixiContainer>
);

Dynamic Extension

Components can be extended dynamically during runtime:

import { extend } from "@pixi/react";
import { useState, useEffect } from "react";

const DynamicExtensionExample = () => {
  const [isExtended, setIsExtended] = useState(false);

  useEffect(() => {
    // Dynamically load and extend components
    import("pixi.js").then(({ NineSlicePlane, SimplePlane }) => {
      extend({ NineSlicePlane, SimplePlane });
      setIsExtended(true);
    });
  }, []);

  if (!isExtended) {
    return <pixiText text="Loading components..." />;
  }

  return (
    <pixiContainer>
      <pixiNineSlicePlane 
        texture={texture}
        leftWidth={10}
        topHeight={10}
        rightWidth={10}
        bottomHeight={10}
      />
    </pixiContainer>
  );
};

Type Safety

Extended components maintain full TypeScript support:

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

extend({ Graphics, Container });

// TypeScript will provide full type checking and autocomplete
const TypeSafeScene = () => (
  <pixiContainer
    x={100}        // ✓ Valid Container property
    y={100}        // ✓ Valid Container property
    alpha={0.5}    // ✓ Valid Container property
    // invalidProp={true} // ✗ TypeScript error
  >
    <pixiGraphics
      draw={(graphics) => {
        // Full Graphics API available with type checking
        graphics.setFillStyle({ color: "red" });
        graphics.rect(0, 0, 100, 100);
        graphics.fill();
      }}
      interactive={true}
      onPointerDown={(event) => {
        // Event is properly typed
        console.log(event.global.x, event.global.y);
      }}
    />
  </pixiContainer>
);