{"id":16376506,"url":"https://github.com/marginalhours/dom-particles","last_synced_at":"2025-09-02T08:39:06.371Z","repository":{"id":40829428,"uuid":"163751640","full_name":"marginalhours/dom-particles","owner":"marginalhours","description":"Particle effects in the DOM","archived":false,"fork":false,"pushed_at":"2025-03-21T16:49:45.000Z","size":1755,"stargazers_count":26,"open_issues_count":1,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-09T04:48:19.852Z","etag":null,"topics":["dom","gamedev","incremental-game","javascript-library","particles"],"latest_commit_sha":null,"homepage":"https://marginalhours.github.io/dom-particles/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marginalhours.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-01-01T16:48:55.000Z","updated_at":"2025-03-21T16:41:49.000Z","dependencies_parsed_at":"2025-07-12T22:46:35.915Z","dependency_job_id":null,"html_url":"https://github.com/marginalhours/dom-particles","commit_stats":null,"previous_names":["misterkeefe/dom-particles"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/marginalhours/dom-particles","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marginalhours%2Fdom-particles","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marginalhours%2Fdom-particles/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marginalhours%2Fdom-particles/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marginalhours%2Fdom-particles/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marginalhours","download_url":"https://codeload.github.com/marginalhours/dom-particles/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marginalhours%2Fdom-particles/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273257252,"owners_count":25073529,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-02T02:00:09.530Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dom","gamedev","incremental-game","javascript-library","particles"],"created_at":"2024-10-11T03:24:55.705Z","updated_at":"2025-09-02T08:39:06.318Z","avatar_url":"https://github.com/marginalhours.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dom-particles\n\n[![CircleCI](https://circleci.com/gh/marginalhours/dom-particles.svg?style=shield)](https://circleci.com/gh/marginalhours/dom-particles) [![npm](https://img.shields.io/npm/v/dom-particles.svg)](https://www.npmjs.com/package/dom-particles)\n\nA small JS library to provide particle-style effects within the DOM, without leveraging `\u003ccanvas\u003e` or other techniques.\n\n\n\u003cp float=\"left\"\u003e\n  \u003cimg src=\"./1.gif\" width=\"32%\" /\u003e\n  \u003cimg src=\"./2.gif\" width=\"32%\" /\u003e \n  \u003cimg src=\"./3.gif\" width=\"32%\" /\u003e\n\u003c/p\u003e\n\n\n[Demo Page](http://marginalhours.github.io/dom-particles)\n\n## Quickstart\n\nInclude this `\u003cscript\u003e` tag in the `\u003chead\u003e` of your page:\n\n`\u003cscript type=\"text/javascript\" src='https://unpkg.com/dom-particles'\u003e\u003c/script\u003e`\n\nThen somewhere in the `\u003cbody\u003e` include the following script:\n\n```\n\u003cscript type='text/javascript'\u003e\n  const t = new DomParticles();\n  const c = { x: document.body.clientWidth / 2 , y: document.body.clientHeight / 2 };\n\n  t.addEmitter({\n    position: { x: c.x, y: c.y },\n    particleOptions: {\n      velocity: { y: -50 },\n      contents: 'Hello world'\n    }\n  });\n\u003c/script\u003e\n```\n\n## Alternative installation via NPM\n\n`npm install --save dom-particles`\n\nthen in your code:\n\n```\nimport DomParticles from 'dom-particles'\n\nconst d = new DomParticles();\n...\n\n```\n\n## Development\n\n`git clone` this repository, then:\n\n```\ncd dom-particles\nnpm i\n\n# Uses parcel to start a hot-reloading playground on port 1234\nnpm run dev\n\n# Builds dom-particles.js to lib/\nnpm run build\n\n# Runs unit tests with Mocha\nnpm run test\n\n```\n\n# API Reference\n\n## DomParticles object\n\nThe DomParticles object is the chief way of creating particles and emitters.\n\nBy default, a DomParticles only uses the `requestAnimationFrame` API to update itself\nwhile a particle or emitter is extant. After the last particle or emitter reaches the end of its\nlifespan, the DomParticles will unregister itself and stop updating until the next `add` or `addEmitter` call.\n\n### Options\n\n| Name          | Default             | Remarks                                                                                                                     |\n| ------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------- |\n| `max`         | `100`               | Maximum number of particles on screen at any one time. Global across all emitters                                           |\n| `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. |\n| `tagName`     | `span`              | Tag to use for particle elements                                                                                            |\n| `container`   | document `body` tag | Parent container for all particles. Will have `position:relative` applied to the styles.                                    |\n| `autostart`   | `true`              | If `false`, particles will not be animated until `.start()` is called on the parent `DomParticles` instance                 |\n\n### Methods\n\n- `.addParticle(options)` - Create a particle from the provided `options` object (see below for particle options)\n- `.addEmitter(options)` - Create a particle emitter from the provided `options` object (see below for emitter options)\n- `.start()` - If `autostart: false` was passed to this instance, call this function manually to begin animation.\n- `.reset()` - Removes all particles and emitters.\n- `.clearEmitters()` - Removes all emitters. Existing particles will remain until the end of their lifespan.\n\n## Particles\n\nParticles are created (and returned) by the `add` function on a `DomParticles` object.\nBy default they have a finite lifespan, after which they disappear from the DOM.\n\nAt each frame, the following default update is applied to a particle:\n\n```\nvelocity += acceleration;\nposition += velocity;\n```\n\nThere 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.\n\nVelocity 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.\n\n### Options\n\n| Name           | Default         | Remarks                                                                                                                                                                                                                                                                                                                          |\n| -------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `contents`     | `'.'`           | innerHTML of the particle element                                                                                                                                                                                                                                                                                                |\n| `ttl`          | `1000`          | Set to an integer to destroy this particle after that many milliseconds have elapsed.                                                                                                                                                                                                                                            |\n| `onCreate`     | N/A             | Callback function on particle creation - called with the particle object as its first argument                                                                                                                                                                                                                                   |\n| `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                                                                                                                                                                 |\n| `onDestroy`    | N/A             | Callback function on particle destruction - called with the particle object as its first argument                                                                                                                                                                                                                                |\n| `style`        | `{}`            | object of styles to be applied to the particle. Style values can be arrays, for animation purposes - see section **Styling Particles** below.                                                                                                                                                                                    |\n| `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.                                                                                                                                                                    |\n| `grid`         | `false`         | Set to a number to snap the particle's position to a grid of that size                                                                                                                                                                                                                                                           |\n| `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. |\n| `velocity`     | `{x : 0, y: 0}` | Particle velocity                                                                                                                                                                                                                                                                                                                |\n| `acceleration` | `{x : 0, y: 0}` | Particle acceleration                                                                                                                                                                                                                                                                                                            |\n\n### Methods\n\n- `setText(text)`: Sets the `innerText` of the particle element to `text`\n- `setContents(html)`: Sets the `innerHTML` of the particle element to `html`\n- `updateStyle(styleObject)`: Update particle element styles\n\n### Styling particles\n\nThe `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:\n\n```\nt.add({\n  style: {\n    'backgroundColor': ['#fff', '#000']\n  }\n});\n```\n\nOver the lifetime (`ttl` property) of the particle, the values in this array will be linearly interpolated between\nfor 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.\n\nThe 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.\n\nThere are also some CSS transform properties which are included as separate arguments for ease-of-use. These are as follows:\n\n- `scale` (or just `scaleX` or `scaleY`) - scale the element. This is the _transform_ version of scale, not the general CSS property.\n- `rotation` - rotate the element, but takes lower precedence than the `heading` property.\n- `skew` (or just `skewX` or `skewY`) - skew the element\n\n## Emitters\n\nEmitters are created (and returned) by the `addEmitter` function on a `DomParticles` object. They provide a convenient way to create multiple particles with similar properties.\n\n### Options\n\n| Name              | Default                  | Remarks                                                                                                                                                        |\n| ----------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `maxEmissions`    | `false`                  | Maximum particles to emit. Set to a integer to destroy this emitter after that many have been created.                                                         |\n| `ttl`             | `false`                  | Set to an integer to destroy this emitter after that many milliseconds have elapsed.                                                                           |\n| `emitEvery`       | `500`                    | Number of milliseconds between particle emissions                                                                                                              |\n| `onCreate`        | N/A                      | Callback function on emitter creation - called with the particle object as its first argument                                                                  |\n| `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 |\n| `onDestroy`       | N/A                      | Callback function on emitter destruction - called with the emitter object as its first argument                                                                |\n| `heading`         | `0`                      | Set to a number in range `0`...`2 * Math.PI` to rotate the direction from which particles are emitted.                                                         |\n| `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.                                 |\n| `velocity`        | `{x : 0, y: 0}`          | Emitter velocity                                                                                                                                               |\n| `acceleration`    | `{x : 0, y: 0}`          | Emitter acceleration                                                                                                                                           |\n| `particleOptions` | default particle options | See subsection \"Options\" of the \"Particle\" section.                                                                                                            |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarginalhours%2Fdom-particles","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarginalhours%2Fdom-particles","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarginalhours%2Fdom-particles/lists"}