dom-particles
v1.0.10
Published
Particle effects for and with DOM elements
Downloads
246
Maintainers
misterkeefeReadme
dom-particles
A small JS library to provide particle-style effects within the DOM, without leveraging <canvas> or other techniques.
Quickstart
Include this <script> tag in the <head> of your page:
<script type="text/javascript" src='https://unpkg.com/dom-particles'></script>
Then somewhere in the <body> include the following script:
<script type='text/javascript'>
const t = new DomParticles();
const c = { x: document.body.clientWidth / 2 , y: document.body.clientHeight / 2 };
t.addEmitter({
position: { x: c.x, y: c.y },
particleOptions: {
velocity: { y: -50 },
contents: 'Hello world'
}
});
</script>Alternative installation via NPM
npm install --save dom-particles
then in your code:
import DomParticles from 'dom-particles'
const d = new DomParticles();
...
Development
git clone this repository, then:
cd dom-particles
npm i
# Uses parcel to start a hot-reloading playground on port 1234
npm run dev
# Builds dom-particles.js to lib/
npm run build
# Runs unit tests with Mocha
npm run test
API Reference
DomParticles object
The DomParticles object is the chief way of creating particles and emitters.
By default, a DomParticles only uses the requestAnimationFrame API to update itself
while a particle or emitter is extant. After the last particle or emitter reaches the end of its
lifespan, the DomParticles will unregister itself and stop updating until the next add or addEmitter call.
Options
| Name | Default | Remarks |
| ---- | ------- | ---------------------------------- |
| max | 100 | Maximum number of particles on screen at any one time. Global across all emitters |
| preallocate | 10 | How many particle elements to create by default and add to the DOM. More will be created on-demand, up to the max amount.
| tagName | span | Tag to use for particle elements
| container | document body tag | Parent container for all particles. Will have position:relative applied to the styles.
| autostart | true | If false, particles will not be animated until .start() is called on the parent DomParticles instance
Methods
.addParticle(options)- Create a particle from the providedoptionsobject (see below for particle options).addEmitter(options)- Create a particle emitter from the providedoptionsobject (see below for emitter options).start()- Ifautostart: falsewas passed to this instance, call this function manually to begin animation..reset()- Removes all particles and emitters..clearEmitters()- Removes all emitters. Existing particles will remain until the end of their lifespan.
Particles
Particles are created (and returned) by the add function on a DomParticles object.
By default they have a finite lifespan, after which they disappear from the DOM.
At each frame, the following default update is applied to a particle:
velocity += acceleration;
position += velocity;There are also three update hooks which can be provided in the particle options: onCreate, onUpdate, and onDestroy. All of these are called with the particle object as the first argument. For onUpdate, the second argument is the elapsed time (in fractions of a second, so 1.0 is one second) since the last onUpdate call.
Velocity and acceleration are specified in units of pixels per second. For example, a particle with a ttl of 1000 milliseconds and a velocity of { x: 10 } will travel ten pixels to the right during its lifespan.
Options
| Name | Default | Remarks |
| ---- | ------- | ----------------------------------- |
| contents | '.' | innerHTML of the particle element |
| ttl | 1000 | Set to an integer to destroy this particle after that many milliseconds have elapsed. |
| onCreate | N/A | Callback function on particle creation - called with the particle object as its first argument |
| onUpdate | N/A | Callback function on particle update - called with the particle object as its first argument, and elapsed time since last onUpdate call as the second argument |
| onDestroy | N/A | Callback function on particle destruction - called with the particle object as its first argument |
| style | {} | object of styles to be applied to the particle. Style values can be arrays, for animation purposes - see section Styling Particles below.
| heading | false | Set to a number in range 0...2 * Math.PI to manually control the particle heading in an onUpdate handler, otherwise animate using the rotation style.
| grid | false | Set to a number to snap the particle's position to a grid of that size
| position | {x : 0, y: 0} | Particle position. If particle is created by an emitter, this is taken to be relative to the emitter's position; if not, it's taken to be relative to the container element of the parent DomParticles object. For convenience, components which are zero need not be specified: {x: 1} and {y: 1} are both valid vectors. |
| velocity | {x : 0, y: 0} | Particle velocity |
| acceleration | {x : 0, y: 0} | Particle acceleration |
Methods
setText(text): Sets theinnerTextof the particle element totextsetContents(html): Sets theinnerHTMLof the particle element tohtmlupdateStyle(styleObject): Update particle element styles
Styling particles
The style property of a particle options object, or a particleOptions object passed to an Emitter, is not limited to static properties or getters. You can pass an array of values for a specific property, like so:
t.add({
style: {
'backgroundColor': ['#fff', '#000']
}
});Over the lifetime (ttl property) of the particle, the values in this array will be linearly interpolated between
for the purpose of the particle's actual style at a particular moment in time. In the above example, a particle with a ttl of 500 milliseconds will begin life at t = 0 with a white background but end it at t = 500 with a black one.
The array of values can be any length. Most simple CSS properties (colours; unit + value eg 1px, 2em etc) are supported. Compound properties have to be manipulated component-by-component.
There are also some CSS transform properties which are included as separate arguments for ease-of-use. These are as follows:
scale(or justscaleXorscaleY) - scale the element. This is the transform version of scale, not the general CSS property.rotation- rotate the element, but takes lower precedence than theheadingproperty.skew(or justskewXorskewY) - skew the element
Emitters
Emitters are created (and returned) by the addEmitter function on a DomParticles object. They provide a convenient way to create multiple particles with similar properties.
Options
| Name | Default | Remarks |
| ---- | ------- | ----------------------------------- |
| maxEmissions | false | Maximum particles to emit. Set to a integer to destroy this emitter after that many have been created. |
| ttl | false | Set to an integer to destroy this emitter after that many milliseconds have elapsed. |
| emitEvery | 500 | Number of milliseconds between particle emissions
| onCreate | N/A | Callback function on emitter creation - called with the particle object as its first argument |
| onUpdate | N/A | Callback function on emitter update - called with the emitter object as its first argument, and elapsed time since last onUpdate call as the second argument |
| onDestroy | N/A | Callback function on emitter destruction - called with the emitter object as its first argument |
| heading | 0 | Set to a number in range 0...2 * Math.PI to rotate the direction from which particles are emitted.
| position | {x : 0, y: 0} | Emitter position. Particles emitted from this emitter will have a position relative to the emitter's position, not the origin. |
| velocity | {x : 0, y: 0} | Emitter velocity |
| acceleration | {x : 0, y: 0} | Emitter acceleration |
| particleOptions | default particle options | See subsection "Options" of the "Particle" section. |