buchenberg.github.io/poop-cannon

You can install this module as a component from NPM:

npm install --save poop-cannon

You can then require('poop-cannon'); to use it in your project build. Note: this is a client component, and will not run in Node. You will need to build your project with something like webpack in order to use this.

You can also include this library in your HTML page directly from a CDN:

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/poop.browser.min.js"></script>

Note: you should use the latest version at the time that you include your project. You can see all versions on the releases page.

Thank you for joining me in this very important message about motion on your website. See, not everyone likes it, and some actually prefer no motion. They have ways to tell us about it and we should listen. While I don't want to go as far as tell you not to have poop on your page just yet, I do want to make it easy for you to respect what your users want. There is a disableForReducedMotion option you can use so that users that have trouble with chaotic animations don't need to struggle on your website. This is disabled by default, but I am considering changing that in a future major release. If you have strong feelings about this, please let me know. For now, please poop responsibly.

When installed from npm, this library can be required as a client component in your project build. When using the CDN version, it is exposed as a poop function on window.

poop takes a single optional object. When window.Promise is available, it will return a Promise to let you know when it is done. When promises are not available (like in IE), it will return null. You can polyfill promises using any of the popular polyfills. You can also provide a promise implementation to poop through:

const MyPromise = require('some-promise-lib');
const poop = require('poop-cannon');
poop.Promise = MyPromise;

If you call poop multiple times before it is done, it will return the same promise every time. Internally, the same canvas element will be reused, continuing the existing animation with the new poop added. The promise returned by each call to poop will resolve once all animations are done.

The poop parameter is a single optional options object, which has the following properties:

• particleCount Integer (default: 50): The number of poop to launch. More is always fun... but be cool, there's a lot of math involved.
• angle Number (default: 90): The angle in which to launch the poop, in degrees. 90 is straight up.
• spread Number (default: 45): How far off center the poop can go, in degrees. 45 means the poop will launch at the defined angle plus or minus 22.5 degrees.
• startVelocity Number (default: 45): How fast the poop will start going, in pixels.
• decay Number (default: 0.9): How quickly the poop will lose speed. Keep this number between 0 and 1, otherwise the poop will gain speed. Better yet, just never change it.
• gravity Number (default: 1): How quickly the particles are pulled down. 1 is full gravity, 0.5 is half gravity, etc., but there are no limits. You can even make particles go up if you'd like.
• drift Number (default: 0): How much to the side the poop will drift. The default is 0, meaning that they will fall straight down. Use a negative number for left and positive number for right.
• ticks Number (default: 200): How many times the poop will move. This is abstract... but play with it if the poop disappear too quickly for you.
• origin Object: Where to start firing poop from. Feel free to launch off-screen if you'd like.
  • origin.x Number (default: 0.5): The x position on the page, with 0 being the left edge and 1 being the right edge.
  • origin.y Number (default: 0.5): The y position on the page, with 0 being the top edge and 1 being the bottom edge.
• colors Array<String>: An array of color strings, in the HEX format... you know, like #bada55.
• shapes Array<String>: An array of shapes for the poop. The possible values are square, circle, and star. The default is to use both squares and circles in an even mix. To use a single shape, you can provide just one shape in the array, such as ['star']. You can also change the mix by providing a value such as ['circle', 'circle', 'square'] to use two third circles and one third squares.
• scalar Number (default: 1): Scale factor for each poop particle. Use decimals to make the poop smaller. Go on, try teeny tiny poop, they are adorable!
• zIndex Integer (default: 100): The poop should be on top, after all. But if you have a crazy high page, you can set it even higher.
• disableForReducedMotion Boolean (default: false): Disables poop entirely for users that prefer reduced motion. The poop() promise will resolve immediately in this case.

This method creates an instance of the poop function that uses a custom canvas. This is useful if you want to limit the area on your page in which poop appear. By default, this method will not modify the canvas in any way (other than drawing to it).

Canvas can be misunderstood a bit though, so let me explain why you might want to let the module modify the canvas just a bit. By default, a canvas is a relatively small image -- somewhere around 300x150, depending on the browser. When you resize it using CSS, this sets the display size of the canvas, but not the image being represented on that canvas. Think of it as loading a 300x150 jpeg image in an img tag and then setting the CSS for that tag to 1500x600 -- your image will end up stretched and blurry. In the case of a canvas, you need to also set the width and height of the canvas image itself. If you don't want to do that, you can allow poop to set it for you.

Note also that you should persist the custom instance and avoid initializing an instance of poop with the same canvas element more than once.

The following global options are available:

• resize Boolean (default: false): Whether to allow setting the canvas image size, as well as keep it correctly sized if the window changes size (e.g. resizing the window, rotating a mobile device, etc.). By default, the canvas size will not be modified.
• useWorker Boolean (default: false): Whether to use an asynchronous web worker to render the poop animation, whenever possible. This is turned off by default, meaning that the animation will always execute on the main thread. If turned on and the browser supports it, the animation will execute off of the main thread so that it is not blocking any other work your page needs to do. Using this option will also modify the canvas, but more on that directly below -- do read it. If it is not supported by the browser, this value will be ignored.
• disableForReducedMotion Boolean (default: false): Disables poop entirely for users that prefer reduced motion. When set to true, use of this poop instance will always respect a user's request for reduced motion and disable poop for them.

Important: If you use useWorker: true, I own your canvas now. It's mine now and I can do whatever I want with it (don't worry... I'll just put poop inside it, I promise). You must not try to use the canvas in any way (other than I guess removing it from the DOM), as it will throw an error. When using workers for rendering, control of the canvas must be transferred to the web worker, preventing any usage of that canvas on the main thread. If you must manipulate the canvas in any way, do not use this option.

var myCanvas = document.createElement('canvas');
document.body.appendChild(myCanvas);

var myPoop = poop.create(myCanvas, {
  resize: true,
  useWorker: true
});
myPoop({
  particleCount: 100,
  spread: 160
  // any other options from the global
  // poop function
});

Stops the animation and clears all poop, as well as immediately resolves any outstanding promises. In the case of a separate poop instance created with poop.create, that instance will have its own reset method.

poop();

setTimeout(() => {
  poop.reset();
}, 100);

var myCanvas = document.createElement('canvas');
document.body.appendChild(myCanvas);

var myPoop = poop.create(myCanvas, { resize: true });

myPoop();

setTimeout(() => {
  myPoop.reset();
}, 100);

Launch some poop the default way:

poop();

Launch a bunch of poop:

poop({
  particleCount: 150
});

Launch some poop really wide:

poop({
  spread: 180
});

Get creative. Launch a small poof of poop from a random part of the page:

poop({
  particleCount: 100,
  startVelocity: 30,
  spread: 360,
  origin: {
    x: Math.random(),
    // since they fall down, start a bit higher than random
    y: Math.random() - 0.2
  }
});

I said creative... we can do better. Since it doesn't matter how many times we call poop (just the total number of poop in the air), we can do some fun things, like continuously launch more and more poop for 30 seconds, from multiple directions:

// do this for 30 seconds
var duration = 30 * 1000;
var end = Date.now()   duration;

(function frame() {
  // launch a few poop from the left edge
  poop({
    particleCount: 7,
    angle: 60,
    spread: 55,
    origin: { x: 0 }
  });
  // and launch a few from the right edge
  poop({
    particleCount: 7,
    angle: 120,
    spread: 55,
    origin: { x: 1 }
  });

  // keep going until we are out of time
  if (Date.now() < end) {
    requestAnimationFrame(frame);
  }
}());