A common performance trick in EaselJS is to layer multiple Stages, and only update content on the Stage instance that changes. For example, a background might contain an complex scene with interactive elements or UI, and an overlapping foreground scene that has animated sprites that is updated frequently. Layering stages can you minimize how often the complex content is rendered.

An issue arises if both stages (or even just the background) have interactivity. HTML DOM elements block mouse interaction with elements that are below their bounding rectangles. The CSS pointer-events API addresses this for individual elements (and its fairly well-supported now!). But when working with EaselJS, which draws content to a single square element, the need arises to let mouse events conditionally pass-through canvases higher in the DOM order.

The nextStage property

Good News! There is a nextStage property on the Stage, built specifically to address this need. Initially added in EaselJS 0.7, and super-charged in 0.8, the nextStage property (link to docs) properly throttles all mouse events not handled on the current stage to the “next” stage.

The nextStage is super simple to apply, and you can layer stages to your heart’s content.

var stage1 = new createjs.Stage(“topCanvas”);
var stage2 = new createjs.Stage(“bottomCanvas”);
stage1.nextStage = stage2;

The “top” canvas should be higher in the DOM order, since it needs to intercept DOM events, and pass them to the next canvas if necessary. EaselJS will relay all DisplayObject mouse events, and even makes sure lower stage events, such as “mouseenter” and “mouseleave” are triggered properly.

Demos and Examples

For a full demo, check out the “TwoStages” example in the EaselJS GitHub, or the live example on CodePen. A StageGL demo is available as well, showing interaction between 2D Stage instances, and WebGL-accelerated StageGL instances. Pair this technique with other performance-improving techniques, such as liberal use of “mouseChildren” and “mouseEnabled” to optimize your HTML5 apps and websites!

Like this article? We are planning to release more mini-articles, including more performance tips and exposés on obscure or advanced features. Let us know in the comments!