Skip to content

PixiJS Masks — Clipping and Revealing Content

DodaTech Updated 2026-06-28 3 min read

In this tutorial, you will learn about PixiJS Masks. We cover key concepts, practical examples, and best practices to help you master this topic.

PixiJS masks clip display objects to specific shapes or alpha channels, enabling reveal effects, circular portraits, and custom clipping regions.

What You'll Learn

By the end of this guide, you will create shape masks using Graphics, apply alpha masks with textures, mask entire containers, animate mask position and scale, and combine masks with filters for advanced effects.

Shape Mask

var mask = new PIXI.Graphics();
mask.beginFill(0xffffff);
mask.drawCircle(150, 150, 80);
mask.endFill();

sprite.mask = mask;

Alpha Mask

var alphaMask = PIXI.Sprite.from('mask-texture.png');
container.mask = alphaMask;
// White areas of mask-texture reveal, black hides

Container Mask

var group = new PIXI.Container();
group.addChild(sprite1);
group.addChild(sprite2);

var circleMask = new PIXI.Graphics();
circleMask.beginFill(0xffffff);
circleMask.drawCircle(200, 150, 100);
circleMask.endFill();

group.mask = circleMask;
app.stage.addChild(group);

Animated Mask

app.ticker.add(function() {
    circleMask.x = Math.sin(Date.now() * 0.002) * 50;
    circleMask.y = Math.cos(Date.now() * 0.003) * 30;
    circleMask.scale.set(1 + Math.sin(Date.now() * 0.001) * 0.2);
});

Common Mistakes

1. Mask Not Added to Stage

The mask graphic must be added to the stage or the same parent as the masked object.

2. Mask Alpha Not Set

Shape masks use the drawing color. Fill with any non-zero alpha color. The color does not matter, only the shape.

3. Alpha Mask Not Using Sprite

Alpha masks require a PIXI.Sprite with a texture. Graphics do not work as alpha mask sources.

4. Performance With Many Masks

Each mask creates a stencil buffer operation. Too many masks slow rendering.

5. Mask Position Not Tracking

If the masked object moves, the mask position should update accordingly or be in the same container.

Practice Questions

Q1: How do you create a shape mask? A: Create a Graphics object and set it as the mask property of the target.

Q2: What is the difference between shape mask and alpha mask? A: Shape mask clips to a geometric shape. Alpha mask uses a texture's alpha channel.

Q3: Can you mask a container? A: Yes. Set container.mask to a Graphics or Sprite.

Q4: How do you remove a mask? A: Set object.mask = null.

Q5: Can masks be animated? A: Yes. Animate the mask's position, scale, or rotation in the ticker.

Challenge: Build a circular profile picture component. The image should be clipped to a circle with a thin border. On hover, the mask scales up slightly and a shadow filter appears.

FAQ

Does masking work on canvas renderer?

Yes. PixiJS masks work on both WebGL and Canvas renderers.

Can I use text as a mask?

Yes. Render text to a RenderTexture and use it as an alpha mask.

What is the performance impact of masks?

Masks trigger stencil buffer operations. Use sparingly on mobile.

Can I invert a mask?

No native invert. Draw the mask shape in reverse or use a custom filter.

Can I mask a filter?

Apply the mask to the filtered object, not the filter itself.

Try It Yourself

Create a circular reveal mask.

<!DOCTYPE html>
<html>
<head>
    <title>PixiJS Masks</title>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/pixi.js/7.3/pixi.min.js"></script>
</head>
<body style="font-family:sans-serif;padding:20px;">
<h2>Mask Demo</h2>
<script>
var app = new PIXI.Application({ width: 400, height: 350, background: 0xf5f5f5 });
document.body.appendChild(app.view);

// Create a colorful background
var bg = new PIXI.Graphics();
bg.beginFill(0x4ecdc4);
bg.drawRect(0, 0, 200, 200);
bg.endFill();
bg.beginFill(0xff6b35);
bg.drawRect(200, 0, 200, 200);
bg.endFill();
bg.beginFill(0x2a9d8f);
bg.drawRect(0, 200, 200, 200);
bg.endFill();
bg.beginFill(0xe8a87c);
bg.drawRect(200, 200, 200, 200);
bg.endFill();

// Add text
var text = new PIXI.Text('Masked Content', { fontSize: 24, fill: '#ffffff', fontWeight: 'bold' });
text.x = 100;
text.y = 160;

var content = new PIXI.Container();
content.addChild(bg);
content.addChild(text);

app.stage.addChild(content);

// Circle mask
var mask = new PIXI.Graphics();
mask.beginFill(0xffffff);
mask.drawCircle(200, 175, 0);
mask.endFill();
app.stage.addChild(mask);
content.mask = mask;

// Animate mask reveal
var radius = 0;
var expanding = true;

app.ticker.add(function() {
    if (expanding) {
        radius += 2;
        if (radius >= 175) expanding = false;
    } else {
        radius -= 2;
        if (radius <= 0) expanding = true;
    }
    mask.clear();
    mask.beginFill(0xffffff);
    mask.drawCircle(200, 175, radius);
    mask.endFill();
});
</script>
</body>
</html>

What's Next

Explore blend modes.

Blend Modes — Blend modes. Particles — Particle effects.

← Previous PixiJS Filters — Applying Visual Effects Next → PixiJS Blend Modes — Compositing Visual Layers

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro

Home Browse Pixijs