pixijs/pixijs-blend-modes

Set container.blendMode to composite display objects with GPU blend equations (standard modes) or filter-based advanced modes. Blend-mode transitions break render batches, so group like-mode siblings together.

Quick Start

const light = new Sprite(await Assets.load("light.png"));
light.blendMode = "add";
app.stage.addChild(light);

const shadow = new Sprite(await Assets.load("shadow.png"));
shadow.blendMode = "multiply";
app.stage.addChild(shadow);

import "pixi.js/advanced-blend-modes";
const overlay = new Sprite(await Assets.load("overlay.png"));
overlay.blendMode = "color-burn";
app.stage.addChild(overlay);

Related skills: pixijs-filters (advanced modes use the filter pipeline), pixijs-performance (batching with blend modes), pixijs-color (color manipulation).

Core Patterns

Standard blend modes

Standard modes are built in and use GPU blend equations directly:

import { Sprite } from "pixi.js";

sprite.blendMode = "normal"; // standard alpha compositing (effective default at root)
sprite.blendMode = "add"; // additive (lighten, glow effects)
sprite.blendMode = "multiply"; // multiply (darken, shadow effects)
sprite.blendMode = "screen"; // screen (lighten, dodge effects)
sprite.blendMode = "erase"; // erase pixels from render target
sprite.blendMode = "none"; // no blending, overwrites destination
sprite.blendMode = "inherit"; // inherit from parent (this is the actual default value)
sprite.blendMode = "min"; // keeps minimum of source and destination (WebGL2+ only)
sprite.blendMode = "max"; // keeps maximum of source and destination (WebGL2+ only)

These are hardware-accelerated and cheap. They do not require filters.

Advanced blend modes

Advanced modes require an explicit import to register the extensions. On the WebGL renderer they also require useBackBuffer: true at init time, or PixiJS logs a warning and the blend silently falls back:

import "pixi.js/advanced-blend-modes";
import { Application, Sprite, Assets } from "pixi.js";

const app = new Application();
await app.init({ useBackBuffer: true }); // required for advanced modes on WebGL

const texture = await Assets.load("overlay.png");
const overlay = new Sprite(texture);
overlay.blendMode = "color-burn";

Available advanced modes:

| Mode | Effect | | -------------- | ----------------------------------------------- | | color-burn | Darkens by increasing contrast | | color-dodge | Brightens by decreasing contrast | | darken | Keeps darker of two layers | | difference | Absolute difference | | divide | Divides bottom by top | | exclusion | Similar to difference, lower contrast | | hard-light | Multiply or screen based on top layer | | hard-mix | High contrast threshold blend | | lighten | Keeps lighter of two layers | | linear-burn | Adds and subtracts to darken | | linear-dodge | Adds layers together | | linear-light | Linear burn or dodge based on top layer | | luminosity | Luminosity of top, hue/saturation of bottom | | negation | Inverted difference | | overlay | Multiply or screen based on bottom layer | | pin-light | Replaces based on lightness comparison | | saturation | Saturation of top, hue/luminosity of bottom | | soft-light | Gentle overlay effect | | subtract | Subtracts top from bottom | | vivid-light | Color burn or dodge based on top layer | | color | Hue and saturation of top, luminosity of bottom |

You set advanced blend modes the same way as standard ones, via the blendMode property. They use filters internally, so they cost more than standard modes.

Batch-friendly ordering

Different blend modes break the rendering batch. Order objects to minimize transitions:

import { Container, Sprite } from "pixi.js";

const scene = new Container();
scene.addChild(screenSprite1); // 'screen'
scene.addChild(screenSprite2); // 'screen'
scene.addChild(normalSprite1); // 'normal'
scene.addChild(normalSprite2); // 'normal'

2 draw calls. Alternating order (screen, normal, screen, normal) would produce 4.

Common Mistakes

[HIGH] Not importing advanced-blend-modes extension

Wrong:

import { Sprite } from "pixi.js";

sprite.blendMode = "color-burn"; // silently falls back to normal

Correct:

import "pixi.js/advanced-blend-modes";
import { Sprite } from "pixi.js";

sprite.blendMode = "color-burn";

Advanced blend modes (color-burn, overlay, etc.) require the extension import. Without it, only standard modes (normal, add, multiply, screen) are available. The invalid mode silently falls back.

[MEDIUM] Mixing blend modes across adjacent objects

Different blend modes break the render batch. screen / normal / screen / normal produces 4 draw calls, while screen / screen / normal / normal produces 2. Sort children so objects with the same blend mode are adjacent.

[HIGH] Using the v7 BLEND_MODES enum

Wrong:

import { BLEND_MODES } from "pixi.js";

sprite.blendMode = BLEND_MODES.ADD; // runtime error: BLEND_MODES is undefined

Correct:

sprite.blendMode = "add";

In v8, BLEND_MODES is a TypeScript type only (a union of string literals). There is no runtime enum export, so BLEND_MODES.ADD evaluates to accessing a property on undefined. Use the string form.

[HIGH] Advanced blend modes without useBackBuffer

Wrong:

import "pixi.js/advanced-blend-modes";
await app.init({
  /* no useBackBuffer */
});
sprite.blendMode = "color-burn"; // logs a warning, falls back

Correct:

import "pixi.js/advanced-blend-modes";
await app.init({ useBackBuffer: true });
sprite.blendMode = "color-burn";

Advanced modes read from the back buffer. On WebGL, the blend silently falls back if the back buffer is not enabled. WebGPU enables the back buffer unconditionally.

[MEDIUM] Advanced blend modes clipped or scaled on high-DPI renderers

Advanced blend modes are filter-based and use Filter.defaultOptions, whose resolution defaults to 1. On a high-DPI render target the blended object can look clipped, scaled, or only partially applied.

Wrong:

import "pixi.js/advanced-blend-modes";

sprite.blendMode = "overlay"; // renders at resolution 1, can clip on retina

Correct:

import { Filter } from "pixi.js";
import "pixi.js/advanced-blend-modes";

Filter.defaultOptions.resolution = "inherit"; // set before creating affected objects

sprite.blendMode = "overlay";

Setting Filter.defaultOptions.resolution = "inherit" makes advanced blend modes render at the render target's resolution. This costs more memory and runtime, so apply it where fidelity matters.

API Reference

• Container.blendMode
• OverlayBlend
• ColorBurnBlend
• ColorDodgeBlend
• HardLightBlend
• SoftLightBlend
• DifferenceBlend