- 
-
-
-
- Premium Addons for Elementor is one of the most common plugins for Elementor that offers more than 55 highly customizable Elementor Widgets and Section Add-ons. tsParticles is exclusively included in Premium Particles Section Add-on for Elementor Page Builder. Check It Now.
- Use Premium Addons for Elementor Page Builder and get the chance to include tsParticles in your next WordPress website without the need to write a single line of code. See a Live Example. -
-
-
----
-
-## Presets
-
-There are some presets ready to be used in [this repository](https://github.com/tsparticles/presets), and they also have a bundle file that contains everything
-needed to run.
-
-### Big Circles
-
-[](https://www.jsdelivr.com/package/npm/@tsparticles/preset-big-circles) [](https://www.npmjs.com/package/@tsparticles/preset-big-circles) [](https://www.npmjs.com/package/@tsparticles/preset-big-circles)
-
-This preset loads big colored circles moving upwards on a white background.
-
-[](https://particles.js.org/samples/presets/bigCircles)
-
-You can find the instructions [here](https://github.com/tsparticles/presets/tree/main/presets/bigCircles#readme)
-
-### Bubbles
-
-[](https://www.jsdelivr.com/package/npm/tsparticles) [](https://www.npmjs.com/package/@tsparticles/preset-bubbles) [](https://www.npmjs.com/package/@tsparticles/preset-bubbles)
-
-This preset loads colored bubbles coming from the bottom of the screen on a white background.
-
-[](https://particles.js.org/samples/presets/bubbles)
-
-You can find the instructions [here](https://github.com/tsparticles/presets/tree/main/presets/bubbles#readme)
-
-### Confetti
-
-[](https://www.jsdelivr.com/package/npm/@tsparticles/preset-confetti) [](https://www.npmjs.com/package/@tsparticles/preset-confetti) [](https://www.npmjs.com/package/@tsparticles/preset-confetti)
-
-This preset loads white and red confetti launched from the screen center on a transparent background.
-
-[](https://particles.js.org/samples/presets/confetti)
-
-You can find the instructions [here](https://github.com/tsparticles/presets/tree/main/presets/confetti#readme)
-
-### Fire
-
-[](https://www.jsdelivr.com/package/npm/@tsparticles/preset-fire) [](https://www.npmjs.com/package/@tsparticles/preset-fire) [](https://www.npmjs.com/package/@tsparticles/preset-fire)
-
-This preset loads a faded red to a black background with particles colored like fire and ash sparks.
-
-[](https://particles.js.org/samples/presets/fire)
-
-You can find the instructions [here](https://github.com/tsparticles/presets/tree/main/presets/fire#readme)
-
-### Firefly
-
-[](https://www.jsdelivr.com/package/npm/@tsparticles/preset-firefly) [](https://www.npmjs.com/package/@tsparticles/preset-firefly) [](https://www.npmjs.com/package/@tsparticles/preset-firefly)
+## Features
-This preset loads a mouse trail made with small fading particles like little fireflies.
+- **Lightweight**: Core engine without unnecessary dependencies
+- **Modular**: Load only the features you need (plugins, shapes, updaters)
+- **Framework agnostic**: Works with vanilla JS, React, Vue, Angular, Svelte, and more
+- **Browser ready**: CDN bundles available for immediate use
+- **Highly customizable**: Rich configuration options for particle behavior
-[](https://particles.js.org/samples/presets/firefly)
+## Loading Additional Features
-You can find the instructions [here](https://github.com/tsparticles/presets/tree/main/presets/firefly#readme)
+To extend the engine with more capabilities, load additional packages:
-### Fireworks
-
-[](https://www.jsdelivr.com/package/npm/@tsparticles/preset-fireworks) [](https://www.npmjs.com/package/@tsparticles/preset-fireworks) [](https://www.npmjs.com/package/@tsparticles/preset-fireworks)
-
-This preset loads a beautiful fireworks effect.
-
-[](https://particles.js.org/samples/presets/fireworks)
-
-You can find the instructions [here](https://github.com/tsparticles/presets/tree/main/presets/fireworks#readme)
-
-### Fountain
-
-[](https://www.jsdelivr.com/package/npm/@tsparticles/preset-fountain) [](https://www.npmjs.com/package/@tsparticles/preset-fountain) [](https://www.npmjs.com/package/@tsparticles/preset-fountain)
-
-[](https://particles.js.org/samples/presets/fountain)
-
-You can find the instructions [here](https://github.com/tsparticles/presets/tree/main/presets/fountain#readme)
-
-### Links
-
-[](https://www.jsdelivr.com/package/npm/@tsparticles/preset-links) [](https://www.npmjs.com/package/@tsparticles/preset-links) [](https://www.npmjs.com/package/@tsparticles/preset-links)
-
-[](https://particles.js.org/samples/presets/links)
-
-You can find the instructions [here](https://github.com/tsparticles/presets/tree/main/presets/links#readme)
-
-### Sea Anemone
-
-[](https://www.jsdelivr.com/package/npm/@tsparticles/preset-sea-anemone) [](https://www.npmjs.com/package/@tsparticles/preset-sea-anemone) [](https://www.npmjs.com/package/@tsparticles/preset-sea-anemone)
-
-[](https://particles.js.org/samples/presets/seaAnemone)
-
-You can find the instructions [here](https://github.com/tsparticles/presets/tree/main/presets/seaAnemone#readme)
-
-### Snow
-
-[](https://www.jsdelivr.com/package/npm/@tsparticles/preset-snow) [](https://www.npmjs.com/package/@tsparticles/preset-snow) [](https://www.npmjs.com/package/@tsparticles/preset-snow)
-
-[](https://particles.js.org/samples/presets/snow)
-
-You can find the instructions [here](https://github.com/tsparticles/presets/tree/main/presets/snow#readme)
-
-### Stars
-
-[](https://www.jsdelivr.com/package/npm/@tsparticles/preset-stars) [](https://www.npmjs.com/package/@tsparticles/preset-stars) [](https://www.npmjs.com/package/@tsparticles/preset-stars)
-
-[](https://particles.js.org/samples/presets/stars)
-
-You can find the instructions [here](https://github.com/tsparticles/presets/tree/main/presets/stars#readme)
-
-### Triangles
-
-[](https://www.jsdelivr.com/package/npm/@tsparticles/preset-triangles) [](https://www.npmjs.com/package/@tsparticles/preset-triangles) [](https://www.npmjs.com/package/@tsparticles/preset-triangles)
-
-[](https://particles.js.org/samples/presets/triangles)
-
-You can find the instructions [here](https://github.com/tsparticles/presets/tree/main/presets/triangles#readme)
-
----
-
-## Templates and Resources
-
-You can find some tsParticles related templates [here](https://github.com/tsparticles/templates). The templates are
-created for _Vanilla Javascript_, _ReactJS_, _VueJS_, _Angular_, _SvelteJS_, and other frameworks.
-
-The templates will vary, new ones can be created or older ones updated with the latest features or changed to a better
-style. Check them out once in a while.
-
-If you created some good design with _tsParticles_ feel free to submit a pull request with your cool template, you'll be
-credited as the template author!
-
-- Use Premium Addons for Elementor Page Builder and get the chance to include tsParticles in your next WordPress website without the need to write a single line of code. See a Live Example. -
-{@link Container.sourceOptions}: The options used when the {@link Container} was created, these options will be used only in the constructor. +- {@link Engine.items | tsParticles.items} +- {@link Engine.item | tsParticles.item(index)} -{@link Container.particles}: The particles manager, you can add/remove particles from here. +## Quick runtime example -## Methods +```json +{ + "id": "tsparticles", + "options": { + "particles": { + "move": { + "enable": true + } + } + } +} +``` -{@link Container.play | play()}: Used to resume the animations, can be stopped using {@link pause | pause()}.
-{@link Container.pause | pause()}: Used to pause the animations, can be restarted using {@link play | play()}. +After loading this configuration, you can control the container with `pause()` and `play()`. -{@link Container.destroy | destroy()}: Prepare the instance to destruction, you won't retrieve this instance anymore. Only if you have a variable set with it. +## Main properties -{@link Container.exportImage | exportImage(callback, type?, quality?)}: Exports an image of the canvas (without the background property if set), type and quality are optional and are the image output type and quality.
-{@link Container.exportConfiguration | exportConfiguration()}: Exports the current configuration in JSON, returns a string +- {@link Container.id}: container id, usually matching the target DOM element id +- {@link Container.options}: current live options +- {@link Container.sourceOptions}: original options used during construction +- {@link Container.particles}: particles manager (add/remove and runtime operations) -{@link Container.start | start()}: Starts the container, it's different from {@link play | play()}, this will reload everything.
-{@link Container.stop | stop()}: Stops the container, it's different from {@link pause | pause()}, this will clean up what need to be reloaded.
-{@link Container.refresh | refresh()}: Restarts the container, just a {@link stop | stop()}/{@link start | start()} shortcut. +If you mutate `container.options` at runtime, call {@link Container.refresh | refresh()} to apply changes consistently. -{@link Container.loadTheme | loadTheme(name)}: Sets the specified theme reloading options, if name is `undefined` the default theme will be used (if set) +## Main methods + +- {@link Container.play | play()}: resume animation +- {@link Container.pause | pause()}: pause animation +- {@link Container.start | start()}: (re)start container with full initialization +- {@link Container.stop | stop()}: stop and cleanup runtime resources +- {@link Container.refresh | refresh()}: shortcut for `stop()` + `start()` +- {@link Container.destroy | destroy()}: destroy instance and release resources + +## Export methods + +- {@link Container.exportImage | exportImage(callback, type?, quality?)}: export the canvas image (without configured background) +- {@link Container.exportConfiguration | exportConfiguration()}: export current config as JSON string + +## Themes + +- {@link Container.loadTheme | loadTheme(name)}: apply a theme and reload options +- If `name` is `undefined`, the default theme is used (if configured) + +## Related docs + +- Options reference map: [Options](./Options.md) +- Color formats: [Color](./Color.md) diff --git a/markdown/Options.md b/markdown/Options.md index c97ac74016e..954aee737c6 100644 --- a/markdown/Options.md +++ b/markdown/Options.md @@ -1,30 +1,138 @@ -# **_Options_** - -| property | option type | example | notes | -| ------------------------ | -------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `autoPlay` | `boolean` | `true` / `false` | | -| `background` | `object` | | See Background options here {@link IBackground} | -| `backgroundMask` | `object` | | See Background Mask options here {@link IBackgroundMask} | -| `detectRetina` | `boolean` | `true` / `false` | Replaces the old `retina_detect` property | -| `duration` | `number` / `range` | `60` / `{ min: 30, max: 90 }` | The particles effect duration in seconds | -| `fpsLimit` | `number` | `60` | _Defaults to `60`_, replaces the old `fps_limit` property | -| `fullScreen` | `object` / `boolean` | {@link IFullScreen} or `true` / `false` | See Full Screen options here {@link IFullScreen} | -| `interactivity` | `object` | | See Interactivity options here {@link IInteractivity} | -| `manualParticles` | `array` | | An array of Manual Particles object. See Manual Particles documentation here {@link IManualParticle } | -| `motion` | `object` | | See Motion options here {@link IMotion here} | -| `particles` | `object` | | See Particles options here {@link IParticlesOptions} | -| `pauseOnBlur` | `boolean` | `true` / `false` | Pauses the animations when the page isn't on foreground | -| `pauseOnOutsideViewport` | `boolean` | `true` / `false` | Pauses the animations when the element is out of the viewport | -| `preset` | `string` / `array` | `"basic"`
`[ "links", "confetti" ]` | You can use this property to load one or more presets for focusing on important properties and not all config. You can find presets on `npm` [here](https://www.npmjs.com/search?q=tsparticles-preset) | -| `responsive` | `array` | | See Responsive options here {@link IResponsive} | -| `themes` | `array` | | It's an array of Theme object, you can see the structure here {@link ITheme} | - -## Plugins - -These options are not part of the slim bundle - -| property | option type | example | notes | -| ------------- | ------------------ | ------- | ----------------------------------------------- | -| `absorbers` | `object` / `array` | | See Absorbers options here {@link IAbsorber} | -| `emitters` | `object` / `array` | | See Emitter options here {@link IEmitter} | -| `polygonMask` | `object` | | See Particles options here {@link IPolygonMask} | +# Options + +This page is the main map for root options. + +Use it to choose where to start, then jump to the detailed guides for each option group. For full type details, use the API reference too: + +-
| -HEX sample - -```json -{ - "color": "#bada55" -} -``` - - | --HEX IColor sample +### Solid color ```json { - "color": { - "value": "#bada55" + "background": { + "color": "#0f172a" } } ``` - | --Rgb sample +### Semi-transparent color ```json { - "color": { - "value": { - "r": 255, - "g": 127, - "b": 0 - } + "background": { + "color": { + "value": "#0ea5e9" + }, + "opacity": 0.2 } } ``` - | --Hsl sample +### Background image ```json { - "color": { - "h": 180, - "s": 100, - "l": 50 + "background": { + "image": "url('https://particles.js.org/images/background3.jpg')", + "position": "50% 50%", + "repeat": "no-repeat", + "size": "cover" } } ``` - - | -
| -HEX sample +### Enable default mask behavior ```json { - "color": "#bada55" -} -``` - - | --HEX IColor sample - -```json -{ - "color": { - "value": "#bada55" + "backgroundMask": { + "enable": true } } ``` - | --Rgb sample +### Custom composite and cover ```json { - "color": { - "value": { - "r": 255, - "g": 127, - "b": 0 + "backgroundMask": { + "enable": true, + "composite": "destination-out", + "cover": { + "color": { + "value": "#111827" + }, + "opacity": 0.9 } } } ``` - - | --Hsl sample - -```json -{ - "color": { - "h": 180, - "s": 100, - "l": 50 - } -} -``` - - | -
` via CSS.
+
+## Common pitfalls
+
+- Setting `zIndex: -1` but keeping `detectsOn: "canvas"` — mouse events will not reach the canvas because it is behind other elements
+- Using `fullScreen: false` without giving the target element explicit dimensions — the canvas will have zero size
+- Using `fullScreen: true` inside a small container `
` — the canvas will still expand to full viewport
+
+## Related docs
+
+- Interactivity (detectsOn): [Interactivity](./Interactivity.md)
+- Options root: [Options](../Options.md)
diff --git a/markdown/Options/Interactivity.md b/markdown/Options/Interactivity.md
index 5c10a53db49..f1510ff285b 100644
--- a/markdown/Options/Interactivity.md
+++ b/markdown/Options/Interactivity.md
@@ -1,23 +1,64 @@
# Interactivity
-- [detectsOn](#detects-on)
-- [events](#events)
-- [modes](#modes)
+Controls how tsParticles responds to mouse and touch interactions.
-## Detects On
+## Properties
-This property is used to determine which HTML element should catch mouse interaction.
+| Key | Type | Notes |
+| ----------- | -------- | ----------------------------------------------------------------------------------------------- |
+| `detectsOn` | `string` | Which element catches interactions; see below |
+| `events` | `object` | Which events are enabled and which modes they trigger — see [Events](./Interactivity/Events.md) |
+| `modes` | `object` | Fine-tuning parameters for each mode — see [Modes](./Interactivity/Modes.md) |
-The valid values are:
+## detectsOn
-- `"canvas"`: Only the particles canvas will be targeted
-- `"parent"`: Only the particles canvas parent will be targeted
-- `"window"`: The full window will be targeted, this will work perfectly with a negative z-index positioned canvas
+Determines which HTML element listens for mouse/touch events.
-## Events
+| Value | Behavior |
+| ---------- | -------------------------------------------------------------------- |
+| `"canvas"` | Only the particles canvas is targeted |
+| `"parent"` | The canvas parent element is targeted |
+| `"window"` | The full window is targeted — works with negative `z-index` canvases |
-See Events documentation {@link IEvents | here}
+Use `"window"` when the canvas is positioned behind page content (e.g. as a background layer with `z-index: -1`).
-## Modes
+## Quick example
-See Modes documentation {@link IModes | here}
+```json
+{
+ "interactivity": {
+ "detectsOn": "canvas",
+ "events": {
+ "onHover": {
+ "enable": true,
+ "mode": "repulse"
+ },
+ "onClick": {
+ "enable": true,
+ "mode": "push"
+ },
+ "resize": true
+ },
+ "modes": {
+ "repulse": {
+ "distance": 150
+ },
+ "push": {
+ "quantity": 4
+ }
+ }
+ }
+}
+```
+
+## Common pitfalls
+
+- Using `detectsOn: "canvas"` when the canvas is behind page content — hover/click events won't fire; use `"window"` instead
+- Enabling a mode in `events` but not configuring its options in `modes`
+- Forgetting to load interaction plugins (`@tsparticles/slim` or higher) for modes like `bubble`, `connect`, `grab`
+
+## Related docs
+
+- Events: [Events](./Interactivity/Events.md)
+- Modes: [Modes](./Interactivity/Modes.md)
+- Options root: [Options](../Options.md)
diff --git a/markdown/Options/Interactivity/Click.md b/markdown/Options/Interactivity/Click.md
index 4e81c448b4e..68c72c751f2 100644
--- a/markdown/Options/Interactivity/Click.md
+++ b/markdown/Options/Interactivity/Click.md
@@ -1,6 +1,44 @@
# On Click Event
-| key | option type | example | notes |
-| -------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
-| `enable` | `boolean` | `true` / `false` | |
-| `mode` | `string`
`array` | `"attract"`
`"bubble"`
`"pause"`
`"push"`
`"remove"`
`"repulse"`
`"trail"`
`"emitter"`
`"absorber"` | `"emitter"` and `"absorber"` are not used by slim bundle | +Configures interactions triggered by click/tap events. + +## Properties + +| Key | Type | Example | Notes | +| -------- | ------------------ | -------------------------------------------------------------------------------- | ---------------------------------- | +| `enable` | `boolean` | `true` / `false` | Enables click interaction handling | +| `mode` | `string` / `array` | `"push"`, `"remove"`, `"repulse"`, `"bubble"`, `"attract"`, `"pause"`, `"trail"` | One or multiple click modes | + +`"emitter"` and `"absorber"` modes require their related plugin packages. + +## Quick examples + +### Add particles on click + +```json +{ + "interactivity": { + "events": { + "onClick": { + "enable": true, + "mode": "push" + } + } + } +} +``` + +### Combine push and bubble + +```json +{ + "interactivity": { + "events": { + "onClick": { + "enable": true, + "mode": ["push", "bubble"] + } + } + } +} +``` diff --git a/markdown/Options/Interactivity/Div.md b/markdown/Options/Interactivity/Div.md index d1385d74132..9e156d1ca71 100644 --- a/markdown/Options/Interactivity/Div.md +++ b/markdown/Options/Interactivity/Div.md @@ -1,8 +1,29 @@ -# On Div "Event" - -| key | option type | example | notes | -| ----------- | ----------------------- | ------------------------------------------- | ---------------------------------------------- | -| `enable` | `boolean` | `true` / `false` | | -| `mode` | `string` | `"bounce"`
`"bubble"`
`"repulse"` | | -| `selectors` | `string`
`array` | a single or an array of DOM CSS selectors | replaces the old `el` and `elementId` property | -| `type` | `string` | `"circle"`
`"rectangle"` | The div shape type | +# On Div Event + +Configures interactions bound to specific DOM elements. + +## Properties + +| Key | Type | Example | Notes | +| ----------- | ------------------ | ----------------------------------- | ---------------------------------------------------- | +| `enable` | `boolean` | `true` / `false` | Enables div-targeted interactions | +| `mode` | `string` / `array` | `"bounce"`, `"bubble"`, `"repulse"` | Interactions applied when hovering matching elements | +| `selectors` | `string` / `array` | `"#cta"` / `[".card", ".hero"]` | CSS selectors to bind | +| `type` | `string` | `"circle"` / `"rectangle"` | Interaction area shape | + +## Quick example + +```json +{ + "interactivity": { + "events": { + "onDiv": { + "enable": true, + "selectors": [".interactive-zone"], + "mode": "repulse", + "type": "circle" + } + } + } +} +``` diff --git a/markdown/Options/Interactivity/Events.md b/markdown/Options/Interactivity/Events.md index 6a4a56ce021..e5e69a4f0a0 100644 --- a/markdown/Options/Interactivity/Events.md +++ b/markdown/Options/Interactivity/Events.md @@ -1,8 +1,98 @@ # Interactivity Events -| key | option type | example | notes | -| --------------- | ----------- | ---------------- | -------------------------------------------------- | -| `onClick` | `object` | | See onClick documentation here {@link IClickEvent} | -| `onDiv` | `object` | | See onDiv documentation here {@link IDivEvent} | -| `onHover` | `object` | | See onHover documentation here {@link IHoverEvent} | -| `events.resize` | `boolean` | `true` / `false` | | +Defines which user interactions trigger particle behaviors. + +## Properties + +| Key | Type | Notes | +| --------- | --------- | --------------------------------------------------------------------------- | +| `onClick` | `object` | Triggered on mouse/touch click — see {@link IClickEvent} | +| `onDiv` | `object` | Triggered when cursor enters a specific DOM element — see {@link IDivEvent} | +| `onHover` | `object` | Triggered when cursor hovers over the canvas — see {@link IHoverEvent} | +| `resize` | `boolean` | When `true`, recalculates layout on window resize (default: `true`) | + +## Quick examples + +### Hover repulse + click push + +```json +{ + "interactivity": { + "events": { + "onHover": { + "enable": true, + "mode": "repulse" + }, + "onClick": { + "enable": true, + "mode": "push" + }, + "resize": true + } + } +} +``` + +### Hover grab (connect nearby particles to cursor) + +```json +{ + "interactivity": { + "events": { + "onHover": { + "enable": true, + "mode": "grab" + } + } + } +} +``` + +### Click remove + +```json +{ + "interactivity": { + "events": { + "onClick": { + "enable": true, + "mode": "remove" + } + } + } +} +``` + +## Available event modes + +`onHover.mode` and `onClick.mode` accept a string or array of strings from these values: + +| Mode | Description | +| ---------- | ---------------------------------------------- | +| `attract` | Pulls particles toward cursor | +| `bounce` | Bounces particles away from cursor | +| `bubble` | Enlarges / changes opacity of nearby particles | +| `connect` | Draws lines between particles near the cursor | +| `grab` | Draws a line from cursor to nearby particles | +| `light` | Simulates a light source at cursor position | +| `parallax` | Moves particles slightly in response to cursor | +| `pause` | Pauses all animation while hovering | +| `push` | Adds new particles at cursor position | +| `remove` | Removes particles near cursor | +| `repulse` | Pushes particles away from cursor | +| `slow` | Slows particles near cursor | +| `trail` | Emits particles along the cursor path | + +> Modes are configured under `interactivity.modes` — see [Modes](./Modes.md). + +## Common pitfalls + +- Enabling events without loading the required interaction plugin (e.g. `connect`, `bubble` require `@tsparticles/slim` or higher) +- Using `onDiv` without targeting a real DOM selector +- Using multiple modes in an array and not configuring each mode's options under `interactivity.modes` + +## Related docs + +- Modes configuration: [Modes](./Modes.md) +- Interactivity root: [Interactivity](../Interactivity.md) +- Options root: [Options](../../Options.md) diff --git a/markdown/Options/Interactivity/Hover.md b/markdown/Options/Interactivity/Hover.md index 58c8ae2d354..70992753f6d 100644 --- a/markdown/Options/Interactivity/Hover.md +++ b/markdown/Options/Interactivity/Hover.md @@ -1,6 +1,42 @@ # On Hover Event -| key | option type | example | notes | -| -------- | ----------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------- | -| `enable` | `boolean` | `true` / `false` | | -| `mode` | `string`
`array` | `"grab"`
`"bubble"`
`"repulse"`
`"connect"`
`["grab", "bubble"]` | the array enables all the specified modes | +Configures interactions triggered while the pointer is over the canvas. + +## Properties + +| Key | Type | Example | Notes | +| -------- | ------------------ | -------------------------------------------------------------------- | --------------------------- | +| `enable` | `boolean` | `true` / `false` | Enables hover interactions | +| `mode` | `string` / `array` | `"grab"`, `"bubble"`, `"repulse"`, `"connect"`, `["grab", "bubble"]` | One or multiple hover modes | + +## Quick examples + +### Repulse on hover + +```json +{ + "interactivity": { + "events": { + "onHover": { + "enable": true, + "mode": "repulse" + } + } + } +} +``` + +### Combined grab and bubble + +```json +{ + "interactivity": { + "events": { + "onHover": { + "enable": true, + "mode": ["grab", "bubble"] + } + } + } +} +``` diff --git a/markdown/Options/Interactivity/Modes.md b/markdown/Options/Interactivity/Modes.md index 066723ab1d2..8134958036b 100644 --- a/markdown/Options/Interactivity/Modes.md +++ b/markdown/Options/Interactivity/Modes.md @@ -1,18 +1,128 @@ # Interactivity Modes -| key | option type | example | notes | -| ----------------------- | ------------------ | ------- | ------------------------------------------------------------------------------------------------------ | -| `connect.distance` | `number` | `100` | | -| `connect.radius` | `number` | `60` | | -| `connect.links.opacity` | `number` | `0...1` | | -| `grab.distance` | `number` | `100` | | -| `grab.links.opacity` | `number` | `0...1` | | -| `bubble.distance` | `number` | `100` | | -| `bubble.size` | `number` | `40` | | -| `bubble.duration` | `number` | `0.4` | seconds | -| `repulse.distance` | `number` | `200` | | -| `repulse.duration` | `number` | `1.2` | seconds | -| `push.quantity` | `number` | `4` | | -| `remove.quantity` | `number` | `4` | | -| `emitter` | `object` / `array` | | See `Emitters` documentation |
-| `absorber` | `object` / `array` | | See `Absorbers` documentation |
+Configures the behavior parameters for each interaction mode.
+Modes are activated through `interactivity.events` — see [Events](./Events.md).
+
+## Connect
+
+Draws temporary lines between particles that are near each other when the cursor is nearby.
+
+| Key | Type | Example | Notes |
+| ----------------------- | -------- | ------- | -------------------------------------------------------- |
+| `connect.distance` | `number` | `100` | Max distance between particles to draw a connection line |
+| `connect.radius` | `number` | `60` | Radius around cursor that activates connect mode |
+| `connect.links.opacity` | `number` | `0.5` | Opacity of the connection lines |
+
+## Grab
+
+Draws a line from the cursor to nearby particles.
+
+| Key | Type | Example | Notes |
+| -------------------- | -------- | ------- | ------------------------------------ |
+| `grab.distance` | `number` | `100` | Max distance from cursor to particle |
+| `grab.links.opacity` | `number` | `0.5` | Opacity of grab lines |
+
+## Bubble
+
+Enlarges or changes the opacity of particles near the cursor.
+
+| Key | Type | Example | Notes |
+| ----------------- | -------- | ------- | ------------------------------------------ |
+| `bubble.distance` | `number` | `100` | Radius of effect |
+| `bubble.size` | `number` | `40` | Target size of particles inside the bubble |
+| `bubble.duration` | `number` | `0.4` | Transition duration in seconds |
+| `bubble.opacity` | `number` | `0.8` | Target opacity inside bubble |
+
+## Repulse
+
+Pushes particles away from the cursor.
+
+| Key | Type | Example | Notes |
+| ------------------ | -------- | ------- | ---------------------------------------------- |
+| `repulse.distance` | `number` | `200` | Radius of repulse effect |
+| `repulse.duration` | `number` | `1.2` | How long particles are pushed before returning |
+| `repulse.speed` | `number` | `1` | Speed of the repulse movement |
+
+## Push
+
+Adds new particles near the cursor on click.
+
+| Key | Type | Example | Notes |
+| --------------- | -------- | ------- | ----------------------------------- |
+| `push.quantity` | `number` | `4` | Number of particles added per click |
+
+## Remove
+
+Removes particles near the cursor on click.
+
+| Key | Type | Example | Notes |
+| ----------------- | -------- | ------- | ------------------------------------- |
+| `remove.quantity` | `number` | `4` | Number of particles removed per click |
+
+## Attract
+
+Pulls particles toward the cursor.
+
+| Key | Type | Example | Notes |
+| ------------------ | -------- | ------- | ---------------------------------------------- |
+| `attract.distance` | `number` | `200` | Radius of attract effect |
+| `attract.duration` | `number` | `0.4` | How long particles are pulled before returning |
+| `attract.speed` | `number` | `1` | Speed of the attract movement |
+
+## Slow
+
+Slows down particles near the cursor.
+
+| Key | Type | Example | Notes |
+| ------------- | -------- | ------- | --------------------------------- |
+| `slow.factor` | `number` | `3` | Slowdown factor (higher = slower) |
+| `slow.radius` | `number` | `200` | Radius of slow effect |
+
+## Emitter / Absorber
+
+These modes are available when the corresponding plugin package is loaded.
+
+| Key | Type | Notes |
+| ---------- | ------------------ | ---------------------------------------------------------------------------------------------- |
+| `emitter` | `object` / `array` | See [Emitters plugin](https://github.com/tsparticles/tsparticles/tree/main/plugins/emitters) |
+| `absorber` | `object` / `array` | See [Absorbers plugin](https://github.com/tsparticles/tsparticles/tree/main/plugins/absorbers) |
+
+## Quick example
+
+```json
+{
+ "interactivity": {
+ "events": {
+ "onHover": { "enable": true, "mode": "repulse" },
+ "onClick": { "enable": true, "mode": ["push", "bubble"] }
+ },
+ "modes": {
+ "repulse": {
+ "distance": 150,
+ "duration": 0.4,
+ "speed": 1
+ },
+ "push": {
+ "quantity": 4
+ },
+ "bubble": {
+ "distance": 200,
+ "size": 20,
+ "duration": 0.5
+ }
+ }
+ }
+}
+```
+
+## Common pitfalls
+
+- Configuring a mode under `modes` but forgetting to enable it in `events`
+- Using emitter/absorber modes without loading their plugin packages
+- Setting very large `distance` values — they scale with canvas size and can degrade performance
+
+## Related docs
+
+- Events: [Events](./Events.md)
+- Interactivity root: [Interactivity](../Interactivity.md)
+- Options root: [Options](../../Options.md)
diff --git a/markdown/Options/ManualParticles.md b/markdown/Options/ManualParticles.md
index d10b4541f87..adc4149d275 100644
--- a/markdown/Options/ManualParticles.md
+++ b/markdown/Options/ManualParticles.md
@@ -1,12 +1,85 @@
# Manual Particles
-- [options](#options)
-- [position](#position)
+Allows placing specific particles at defined positions when the container loads, instead of random spawning.
-## Options
+Useful for creating fixed reference points, logos, or custom visual arrangements.
-See Particles options {@link IParticlesOptions | here}
+## Properties
+
+| Key | Type | Notes |
+| ---------- | -------- | ------------------------------------------------------------------ |
+| `position` | `object` | Canvas position as a percentage — `{ x: 50, y: 50 }` is center |
+| `options` | `object` | Full {@link IParticlesOptions} override for this specific particle |
## Position
-The position specified is not absolute, it will be used as a percent value of the canvas size. If it's not specified a random position will be used.
+Coordinates are expressed as percentages of canvas dimensions, not absolute pixels.
+
+- `{ x: 0, y: 0 }` → top-left corner
+- `{ x: 50, y: 50 }` → center
+- `{ x: 100, y: 100 }` → bottom-right corner
+
+If `position` is omitted, a random position is used.
+
+## Quick examples
+
+### Single centered particle
+
+```json
+{
+ "manualParticles": [
+ {
+ "position": { "x": 50, "y": 50 },
+ "options": {
+ "size": { "value": 20 },
+ "color": { "value": "#ff0000" }
+ }
+ }
+ ]
+}
+```
+
+### Multiple fixed particles at corners
+
+```json
+{
+ "manualParticles": [
+ { "position": { "x": 10, "y": 10 } },
+ { "position": { "x": 90, "y": 10 } },
+ { "position": { "x": 10, "y": 90 } },
+ { "position": { "x": 90, "y": 90 } }]
+}
+```
+
+### Mixed — manual + random
+
+Manual particles are added on top of the normal random `number.value` count.
+
+```json
+{
+ "particles": {
+ "number": { "value": 40 }
+ },
+ "manualParticles": [
+ {
+ "position": { "x": 50, "y": 50 },
+ "options": {
+ "size": { "value": 30 },
+ "color": { "value": "#ffffff" },
+ "move": { "enable": false }
+ }
+ }
+ ]
+}
+```
+
+## Common pitfalls
+
+- Manual particles are **additional** to `number.value` — they do not replace the random pool
+- Omitting `options` gives the manual particle the same config as regular particles — override only what you need
+- Coordinates above `100` or below `0` place the particle outside the visible canvas
+
+## Related docs
+
+- Particles options: [Particles](./Particles.md)
+- Options root: [Options](../Options.md)
diff --git a/markdown/Options/Motion.md b/markdown/Options/Motion.md
index 70ff42d494c..df6423aa33e 100644
--- a/markdown/Options/Motion.md
+++ b/markdown/Options/Motion.md
@@ -1,21 +1,68 @@
# Motion
-- [disable](#disable)
-- [reduce](#reduce)
+Accessibility-aware controls to reduce or disable particle animation for users who prefer reduced motion.
-## Disable
+Respects the [`prefers-reduced-motion`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) media query.
-If set to `true`, disables animations for users with `prefer-reduced-motion` enabled
+## Properties
-## Reduce
+| Key | Type | Default | Notes |
+| --------------- | --------- | ------- | ----------------------------------------------------------------- |
+| `disable` | `boolean` | `false` | Completely stops all animation for `prefers-reduced-motion` users |
+| `reduce.value` | `boolean` | `true` | Reduces (but does not stop) animation instead of disabling it |
+| `reduce.factor` | `number` | `4` | Higher values = more aggressive reduction |
-- [factor](#factor)
-- [value](#value)
+## disable
-### Factor
+When `true`, no animation runs at all for users with `prefers-reduced-motion: reduce`.
-This value will be used inverse, so a higher value will reduce motion a lot
+```json
+{
+ "motion": {
+ "disable": true
+ }
+}
+```
-### Value
+## reduce
-If set to `true`, reduces animations for users with `prefer-reduced-motion` enabled
+When `disable` is `false`, the `reduce` option slows down motion proportionally instead of stopping it entirely.
+
+`factor` is applied inversely — a higher value produces a stronger slowdown.
+
+```json
+{
+ "motion": {
+ "disable": false,
+ "reduce": {
+ "value": true,
+ "factor": 4
+ }
+ }
+}
+```
+
+## Recommended pattern
+
+Use `reduce` for most cases to keep a subtle animation alive while respecting accessibility. Use `disable` only when any animation would be disorienting.
+
+```json
+{
+ "motion": {
+ "disable": false,
+ "reduce": {
+ "value": true,
+ "factor": 10
+ }
+ }
+}
+```
+
+## Common pitfalls
+
+- Ignoring `motion` entirely — `prefers-reduced-motion` users may experience discomfort with fast animations
+- Setting `reduce.factor` too low (e.g. `1`) — has no visible effect on motion speed
+
+## Related docs
+
+- Options root: [Options](../Options.md)
diff --git a/markdown/Options/Particles.md b/markdown/Options/Particles.md
index 3f6d9cf324a..57f795e1a77 100644
--- a/markdown/Options/Particles.md
+++ b/markdown/Options/Particles.md
@@ -1,115 +1,115 @@
# Particles
-- [bounce](#bounce)
-- [collisions](#collisions)
-- [color](#color)
-- [destroy](#destroy)
-- [groups](#groups)
-- [life](#life)
-- [links](#links)
-- [move](#move)
-- [number](#number)
-- [opacity](#opacity)
-- [orbit](#orbit)
-- [reduceDuplicates](#reduce-duplicates)
-- [repulse](#repulse)
-- [roll](#roll)
-- [rotate](#rotate)
-- [shadow](#shadow)
-- [shape](#shape)
-- [size](#size)
-- [stroke](#stroke)
-- [tilt](#tilt)
-- [twinkle](#twinkle)
-- [wobble](#wobble)
-- [zIndex](#z-index)
-
-## Bounce
-
-See Particles Bounce documentation {@link IParticlesBounce | here}
-
-## Collisions
-
-See Particles Collisions documentation {@link ICollisions | here}
-
-## Color
-
-See Particles Color documentation {@link IAnimatableColor | here}
-
-## Destroy
-
-See Particles Destroy documentation {@link IDestroy | here}
-
-## Groups
-
-## Life
-
-See Particles Life documentation {@link ILife | here}
-
-## Links
-
-See Particles Links documentation {@link ILinks | here}
-
-## Move
-
-See Particles Move documentation {@link IMove | here}
-
-## Number
-
-See Particles Number documentation {@link IParticlesNumber | here}
-
-## Opacity
-
-See Particles Opacity documentation {@link IOpacity | here}
-
-## Orbit
-
-See Particles Orbit documentation {@link IOrbit | here}
-
-## Reduce Duplicates
-
-If set to `true` it reduces particles duplicates, picking particles configuration sequentially
-
-## Repulse
-
-See Particles Repulse documentation {@link IParticlesRepulse | here}
-
-## Roll
-
-See Particles Roll documentation {@link IRoll | here}
-
-## Rotate
-
-See Particles Rotate documentation {@link IRotate | here}
-
-## Shadow
-
-See Shadow documentation {@link IShadow | here}
-
-## Shape
-
-See Shape documentation {@link IShape | here}
-
-## Size
-
-See Particles Size documentation {@link ISize | here}
-
-## Stroke
-
-See Particles Stroke documentation {@link IStroke | here}
-
-## Tilt
-
-See Particles Tilt documentation {@link ITilt | here}
-
-## Twinkle
-
-See Particles Twinkle documentation {@link ITwinkle | here}
-
-## Wobble
-
-See Particles Wobble documentation {@link IWobble | here}
-
-## Z Index
-
-See Particles Z Index documentation {@link IZIndex | here}
+Root section for all particle appearance and behavior settings.
+
+Each property controls one aspect of a particle's life cycle.
+Use the links below to navigate to the detailed page for each sub-option.
+
+## Sub-options
+
+| Property | Description | Docs |
+| ------------------ | --------------------------------------------------------------------------- | --------------------------------------- |
+| `bounce` | Bounce behavior when particles hit each other or the canvas edge | {@link IParticlesBounce} |
+| `collisions` | Collision detection and response between particles | [Collisions](./Particles/Collisions.md) |
+| `color` | Base particle color | {@link IAnimatableColor} |
+| `destroy` | What happens when a particle reaches end of life | [Destroy](./Particles/Destroy.md) |
+| `groups` | Define named groups with different settings applied to subsets of particles | — |
+| `life` | Lifespan and delay for finite-lifetime particles | [Life](./Particles/Life.md) |
+| `links` | Lines drawn between nearby particles | [Links](./Particles/Links.md) |
+| `move` | Movement direction, speed, and path | [Move](./Particles/Move.md) |
+| `number` | How many particles exist and density rules | [Number](./Particles/Number.md) |
+| `opacity` | Transparency and animated fading | [Opacity](./Particles/Opacity.md) |
+| `orbit` | Orbital rotation around a center point | {@link IOrbit} |
+| `reduceDuplicates` | When `true`, picks particle configs sequentially instead of randomly | — |
+| `repulse` | Mutual repulsion between particles | {@link IParticlesRepulse} |
+| `roll` | 3D-like rolling effect | [Roll](./Particles/Roll.md) |
+| `rotate` | Rotation angle and speed | [Rotate](./Particles/Rotate.md) |
+| `shadow` | Drop shadow behind particles | [Shadow](./Particles/Shadow.md) |
+| `shape` | Particle visual shape (circle, square, image, emoji, …) | [Shape](./Particles/Shape.md) |
+| `size` | Particle radius and animated grow/shrink | [Size](./Particles/Size.md) |
+| `stroke` | Outline stroke color and width | [Stroke](./Particles/Stroke.md) |
+| `tilt` | Tilt angle and animation | [Tilt](./Particles/Tilt.md) |
+| `twinkle` | Random opacity flicker effect | [Twinkle](./Particles/Twinkle.md) |
+| `wobble` | Lateral wobble movement | [Wobble](./Particles/Wobble.md) |
+| `zIndex` | Depth sorting of particles | [ZIndex](./Particles/ZIndex.md) |
+
+## Minimal practical example
+
+```json
+{
+ "particles": {
+ "color": {
+ "value": "#ffffff"
+ },
+ "links": {
+ "enable": true,
+ "color": "#ffffff",
+ "distance": 150,
+ "opacity": 0.4
+ },
+ "move": {
+ "enable": true,
+ "speed": 1.5
+ },
+ "number": {
+ "value": 60,
+ "density": {
+ "enable": true,
+ "area": 800
+ }
+ },
+ "opacity": {
+ "value": 0.5
+ },
+ "shape": {
+ "type": "circle"
+ },
+ "size": {
+ "value": { "min": 1, "max": 3 }
+ }
+ }
+}
+```
+
+## groups
+
+Particle groups let you define subsets of particles with different configs applied to a fraction of the total count.
+
+```json
+{
+ "particles": {
+ "number": { "value": 100 },
+ "groups": {
+ "small": {
+ "number": { "value": 60 },
+ "size": { "value": 2 },
+ "color": { "value": "#aaaaff" }
+ },
+ "large": {
+ "number": { "value": 40 },
+ "size": { "value": 8 },
+ "color": { "value": "#ff4444" }
+ }
+ }
+ }
+}
+```
+
+## reduceDuplicates
+
+When `true`, particles cycle through configs sequentially instead of picking randomly — useful for guaranteed even distribution.
+
+## Common pitfalls
+
+- Enabling `links` without `@tsparticles/slim` or higher
+- Setting `move.enable: false` and expecting particles to appear animated
+- Forgetting `number.density.enable: true` on responsive layouts — particle count stays fixed regardless of screen size
+- Using a shape type without loading the corresponding shape package
+
+## Related docs
+
+- Options root: [Options](../Options.md)
+- Number: [Number](./Particles/Number.md)
+- Move: [Move](./Particles/Move.md)
+- Links: [Links](./Particles/Links.md)
+- Shape: [Shape](./Particles/Shape.md)
diff --git a/markdown/Options/Particles/Bounce.md b/markdown/Options/Particles/Bounce.md
index 68937437be5..59221ade978 100644
--- a/markdown/Options/Particles/Bounce.md
+++ b/markdown/Options/Particles/Bounce.md
@@ -1,6 +1,42 @@
# Particles Bounce
-| key | option type | example | notes |
-| ------------------ | ------------------ | ----------------------------- | ----- |
-| `horizontal.value` | `number` / `range` | `50` / `{ min: 30, max: 50 }` | |
-| `vertical.value` | `number` / `range` | `50` / `{ min: 30, max: 50 }` | |
+Controls how strongly particles bounce on horizontal and vertical axes after collisions.
+
+## Properties
+
+| Key | Type | Example | Notes |
+| ------------------ | ------------------ | ----------------------------- | ------------------------ |
+| `horizontal.value` | `number` / `range` | `50` / `{ min: 30, max: 50 }` | Horizontal bounce factor |
+| `vertical.value` | `number` / `range` | `50` / `{ min: 30, max: 50 }` | Vertical bounce factor |
+
+## Quick examples
+
+### Symmetric bounce
+
+```json
+{
+ "bounce": {
+ "horizontal": {
+ "value": 50
+ },
+ "vertical": {
+ "value": 50
+ }
+ }
+}
+```
+
+### Softer vertical bounce
+
+```json
+{
+ "bounce": {
+ "horizontal": {
+ "value": { "min": 40, "max": 60 }
+ },
+ "vertical": {
+ "value": 20
+ }
+ }
+}
+```
diff --git a/markdown/Options/Particles/Collisions.md b/markdown/Options/Particles/Collisions.md
index de3a49d0e0b..cfc8d46315d 100644
--- a/markdown/Options/Particles/Collisions.md
+++ b/markdown/Options/Particles/Collisions.md
@@ -1,15 +1,90 @@
# Particles Collisions
-| key | option type | example | notes |
-| --------- | ----------- | --------------------------------------------- | ------------------------------------------------------- |
-| `bounce` | `object` | | See Particles Bounce documentation here {@link IBounce} |
-| `enable` | `boolean` | `true` / `false` | |
-| `overlap` | `object` | | See Particles Collisions Overlap options below |
-| `mode` | `string` | `"absorb"`
`"bounce"`
`"destroy"` | | - -## Particles Collisions Overlap - -| key | option type | example | notes | -| --------- | ----------- | ---------------- | ----- | -| `enable` | `boolean` | `true` / `false` | | -| `retries` | `number` | `1` | | +Controls how particles interact when they intersect each other. + +## Properties + +| Key | Type | Example | Notes | +| --------- | --------- | ------------------------------------- | ----------------------------------------------- | +| `enable` | `boolean` | `true` / `false` | Enables particle-to-particle collision handling | +| `mode` | `string` | `"bounce"` / `"destroy"` / `"absorb"` | Collision behavior | +| `bounce` | `object` | | Bounce tuning options, see {@link IBounce} | +| `overlap` | `object` | | Initial spawn overlap handling | + +## Collision modes + +| Mode | Behavior | +| ----------- | --------------------------------------------------------- | +| `"bounce"` | Particles bounce off each other preserving both particles | +| `"destroy"` | One particle is removed after impact | +| `"absorb"` | One particle absorbs another, increasing size/mass effect | + +## Quick examples + +### Basic bounce collisions + +```json +{ + "collisions": { + "enable": true, + "mode": "bounce" + } +} +``` + +### Arcade-style destructive collisions + +```json +{ + "collisions": { + "enable": true, + "mode": "destroy" + } +} +``` + +### Absorb collisions + +```json +{ + "collisions": { + "enable": true, + "mode": "absorb" + } +} +``` + +## Overlap options + +Controls how initial particles are placed when collisions are enabled. + +| Key | Type | Example | Notes | +| --------- | --------- | ---------------- | ----------------------------------------------------------- | +| `enable` | `boolean` | `true` / `false` | If `false`, overlapping at spawn is prevented | +| `retries` | `number` | `1` | Number of attempts to find a non-overlapping spawn position | + +### Spawn without overlaps + +```json +{ + "collisions": { + "enable": true, + "overlap": { + "enable": false, + "retries": 5 + } + } +} +``` + +## Common pitfalls + +- Enabling collisions with very high particle counts can be expensive in large canvases +- Using `mode: "destroy"` without emitters can reduce particle count quickly +- Setting `overlap.enable: false` with low `retries` can still allow occasional overlaps in crowded scenes + +## Related docs + +- Particles root: [Particles](../Particles.md) +- Move and bounce behavior: [Move](./Move.md) +- Options root: [Options](../../Options.md) diff --git a/markdown/Options/Particles/Color.md b/markdown/Options/Particles/Color.md index d47102fcf0b..fd68c307c86 100644 --- a/markdown/Options/Particles/Color.md +++ b/markdown/Options/Particles/Color.md @@ -1,18 +1,97 @@ # Particles Color -| key | option type | example | notes | -| ------------- | ----------- | ------- | --------------------------------------------------------- | ----- | -| `value` | `object` | | This `value` property is the same described {@link IColor | here} | -| `animation.h` | `object` | | See animation documentation below | -| `animation.s` | `object` | | See animation documentation below | -| `animation.l` | `object` | | See animation documentation below | - -## Particles Color Animation - -| key | option type | example | notes | -| ------------ | ----------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `enable` | `boolean` | `true` / `false` | | -| `offset.max` | `number` | `60` | | -| `offset.min` | `number` | `20` | | -| `speed` | `number` | `40` | Determines the rate (% or ° per second) at which a particle changes its
hue, saturation, or lightness. A `speed` of `0` will set the hsl of
particles to what was initially defined in `value`. | -| `sync` | `boolean` | `true` / `false` | When `sync` is toggled `true`, particles generated will change color in
time with each other for their entire duration. However, when `sync` is
toggled `false`, particles generated begin changing color at the set speed from
their time of appearance, but independently of one another. | +Controls the base color of particles and optional HSL animation over time. + +## Properties + +| Key | Type | Example | Notes | +| ------------- | ----------------------------- | -------------------------------------------------------------------------- | -------------------------------------------- | +| `value` | `string` / `array` / `object` | `"#ffffff"` / `["#ff0000", "#00ff00"]` / `{ "h": 200, "s": 100, "l": 50 }` | Same color model described in {@link IColor} | +| `animation.h` | `object` | | Hue animation options (0-360) | +| `animation.s` | `object` | | Saturation animation options (0-100) | +| `animation.l` | `object` | | Lightness animation options (0-100) | + +## Quick examples + +### Static solid color + +```json +{ + "color": { + "value": "#ffffff" + } +} +``` + +### Random color per particle from a palette + +```json +{ + "color": { + "value": ["#f43f5e", "#06b6d4", "#84cc16", "#f59e0b"] + } +} +``` + +### HSL hue animation (rainbow effect) + +```json +{ + "color": { + "value": { "h": 0, "s": 100, "l": 50 }, + "animation": { + "h": { + "enable": true, + "speed": 40, + "sync": false + } + } + } +} +``` + +### Gentle saturation/lightness breathing + +```json +{ + "color": { + "value": { "h": 200, "s": 60, "l": 50 }, + "animation": { + "s": { + "enable": true, + "speed": 5, + "offset": { "min": 10, "max": 30 }, + "sync": false + }, + "l": { + "enable": true, + "speed": 4, + "offset": { "min": 10, "max": 25 }, + "sync": false + } + } + } +} +``` + +## Color animation properties (`animation.h`, `animation.s`, `animation.l`) + +| Key | Type | Example | Notes | +| ------------ | --------- | ---------------- | ------------------------------------------------------------------------------------------ | +| `enable` | `boolean` | `true` / `false` | Enables animation for the selected channel | +| `offset.min` | `number` | `20` | Minimum random phase offset | +| `offset.max` | `number` | `60` | Maximum random phase offset | +| `speed` | `number` | `40` | Rate of change per second; `0` keeps the initial `value` | +| `sync` | `boolean` | `true` / `false` | If `true`, particles animate in lockstep; if `false`, each particle animates independently | + +## Common pitfalls + +- Using HSL animation with extremely high `speed` values can look like flicker +- Animating all three channels (`h`, `s`, `l`) at high speed can make colors unstable and hard to control +- Setting `sync: true` for all channels can produce a flat global pulse instead of natural variation + +## Related docs + +- Color formats and models: [Color](../../Color.md) +- Particles root: [Particles](../Particles.md) +- Options root: [Options](../../Options.md) diff --git a/markdown/Options/Particles/Destroy.md b/markdown/Options/Particles/Destroy.md index cbb230f8477..5a1cfa86621 100644 --- a/markdown/Options/Particles/Destroy.md +++ b/markdown/Options/Particles/Destroy.md @@ -1,15 +1,50 @@ # Particles Destroy -| key | option type | example | notes | -| ------- | ----------- | ----------------------- | ----- | -| `mode` | `string` | `"none"`
`"split"` | | -| `split` | `object` | | | - -## Particles Destroy Split - -| key | option type | example | notes | -| -------------- | ------------------ | -------------------------- | ---------------------------------------------- | ----- | -| `count` | `number` | `1` | | -| `factor.value` | `number` / `range` | `9` / `{min: 4, max: 9 }` | | -| `particles` | `object` | | See Particles options {@link IParticlesOptions | here} | -| `rate.value` | `number` / `range` | `9` / `{ min: 4, max: 9 }` | | +Controls what happens when a particle reaches its end condition. + +## Properties + +| Key | Type | Example | Notes | +| ------- | -------- | -------------------- | ------------------------------ | +| `mode` | `string` | `"none"` / `"split"` | Destroy behavior | +| `split` | `object` | | Split configuration, see below | + +## Split properties + +| Key | Type | Example | Notes | +| -------------- | ------------------ | -------------------------- | ----------------------------------------------------- | +| `count` | `number` | `1` | Number of generated particles | +| `factor.value` | `number` / `range` | `9` / `{ min: 4, max: 9 }` | Size/speed factor for spawned particles | +| `particles` | `object` | | Child particle options, see {@link IParticlesOptions} | +| `rate.value` | `number` / `range` | `9` / `{ min: 4, max: 9 }` | Spawn intensity | + +## Quick examples + +### Disable destroy behavior + +```json +{ + "destroy": { + "mode": "none" + } +} +``` + +### Split on destroy + +```json +{ + "destroy": { + "mode": "split", + "split": { + "count": 2, + "factor": { + "value": { "min": 3, "max": 6 } + }, + "rate": { + "value": 10 + } + } + } +} +``` diff --git a/markdown/Options/Particles/Group.md b/markdown/Options/Particles/Group.md index e69de29bb2d..10ffeb653e2 100644 --- a/markdown/Options/Particles/Group.md +++ b/markdown/Options/Particles/Group.md @@ -0,0 +1,50 @@ +# Particles Groups + +Defines named particle option groups that can be referenced by emitters, manual particles, or generated particles. + +## Properties + +`groups` is an object map where: + +- key: group id (`"spark"`, `"smoke"`, `"accent"`, ...) +- value: full particle options override for that group + +Each group value supports the same structure as {@link IParticlesOptions}. + +## Quick example + +```json +{ + "particles": { + "groups": { + "spark": { + "number": { + "value": 0 + }, + "color": { + "value": "#f59e0b" + }, + "size": { + "value": 2 + } + }, + "smoke": { + "number": { + "value": 0 + }, + "color": { + "value": "#94a3b8" + }, + "opacity": { + "value": 0.2 + } + } + } + } +} +``` + +## Notes + +- Group definitions do not automatically spawn particles. +- Use emitters, manual particles, or plugin features that target group ids to create grouped particles. diff --git a/markdown/Options/Particles/Life.md b/markdown/Options/Particles/Life.md index 620e8cd7572..7a16ef90b81 100644 --- a/markdown/Options/Particles/Life.md +++ b/markdown/Options/Particles/Life.md @@ -1,21 +1,43 @@ # Particles Life -| key | option type | example | notes | -| ---------- | ----------- | ------- | ----- | -| `count` | `number` | `0` | | -| `delay` | `object` | | | -| `duration` | `object` | | | +Controls particle lifespan and respawn timing. -## Particles Life Delay +## Properties -| key | option type | example | notes | -| ------- | ------------------ | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `value` | `number` / `range` | `0` / `{ min: 1, max: 5 }` | | -| `sync` | `boolean` | `true` / `false` | When `true`, all particles appear at the same time when the browser loads
the page. When `false`, particles appear with the `life.delay` value specified. | +| Key | Type | Example | Notes | +| ---------- | -------- | ------- | ------------------------------------------ | +| `count` | `number` | `0` | Number of life cycles (`0` means infinite) | +| `delay` | `object` | | Delay before each life starts | +| `duration` | `object` | | Active lifetime duration | -## Particles Life Duration +## Delay -| key | option type | example | notes | -| ------- | ------------------ | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| `value` | `number` / `range` | `0` / `{ min: 1, max: 5 }` | | -| `sync` | `boolean` | `true` / `false` | When `true`, the particle durations will be coordinated with one another.
In other words, they will all appear and disappear at the same time. | +| Key | Type | Example | Notes | +| ------- | ------------------ | -------------------------- | ----------------------------------------------------------- | +| `value` | `number` / `range` | `0` / `{ min: 1, max: 5 }` | Delay in seconds | +| `sync` | `boolean` | `true` / `false` | `true`: particles start together, `false`: staggered starts | + +## Duration + +| Key | Type | Example | Notes | +| ------- | ------------------ | -------------------------- | ----------------------------------------------------------- | +| `value` | `number` / `range` | `0` / `{ min: 1, max: 5 }` | Duration in seconds | +| `sync` | `boolean` | `true` / `false` | `true`: particles end together, `false`: independent timing | + +## Quick example + +```json +{ + "life": { + "count": 3, + "delay": { + "value": { "min": 0.5, "max": 2 }, + "sync": false + }, + "duration": { + "value": { "min": 2, "max": 4 }, + "sync": false + } + } +} +``` diff --git a/markdown/Options/Particles/Links.md b/markdown/Options/Particles/Links.md index 42afccbd9ca..8163e5dd832 100644 --- a/markdown/Options/Particles/Links.md +++ b/markdown/Options/Particles/Links.md @@ -1,31 +1,131 @@ # Particles Links -| key | option type | example | notes | -| ----------- | -------------- | ---------------- | --------------------------------------------------------------------------------------------------------------- | -| `blink` | `boolean` | `true` / `false` | This option works with `color` with "random" value, if set to `true` the links will blink with random colors | -| `color` | `color object` | | This `color` object is the same described here {@links IColor} | -| `consent` | `boolean` | `true` / `false` | This option works with `color` with "random" value, if set to `true` the links will have a random common color | -| `distance` | `number` | `150` | | -| `enable` | `boolean` | `true` / `false` | | -| `id` | `string` | `"link1"` | This `id` is optional, when specified the particles with the same link `id` will be linked together, if enabled | -| `opacity` | `number` | `0...1` | | -| `shadow` | `object` | | See shadow documentation below | -| `triangles` | `object` | | See triangles documentation below | -| `warp` | `boolean` | `true` / `false` | | -| `width` | `number` | `1.5` | | +Draws lines between nearby particles, creating a web-like effect. + +> Requires `@tsparticles/slim` or higher (not available in `@tsparticles/basic`). + +## Properties + +| Key | Type | Example | Notes | +| ----------- | --------------------- | ---------------- | -------------------------------------------------------------------------- | +| `enable` | `boolean` | `true` / `false` | Activates link drawing | +| `distance` | `number` | `150` | Max px distance between particles for a link to appear | +| `color` | color object / string | `"#ffffff"` | See {@link IColor} | +| `opacity` | `number` | `0.4` | Link line opacity (0–1) | +| `width` | `number` | `1.5` | Link line width in pixels | +| `blink` | `boolean` | `true` / `false` | When `color` is `"random"`, makes links blink with different random colors | +| `consent` | `boolean` | `true` / `false` | When `color` is `"random"`, all links share one common random color | +| `id` | `string` | `"group1"` | Only particles with the same `id` are linked | +| `warp` | `boolean` | `true` / `false` | Links wrap around canvas edges | +| `shadow` | `object` | | See [Links Shadow](#links-shadow) | +| `triangles` | `object` | | See [Links Triangles](#links-triangles) | + +## Quick examples + +### Basic links web + +```json +{ + "links": { + "enable": true, + "distance": 150, + "color": "#ffffff", + "opacity": 0.4, + "width": 1 + } +} +``` + +### Colored random-blink links + +```json +{ + "links": { + "enable": true, + "distance": 120, + "color": "random", + "blink": true, + "opacity": 0.6 + } +} +``` + +### Links with triangles fill + +```json +{ + "links": { + "enable": true, + "distance": 150, + "color": "#4f46e5", + "triangles": { + "enable": true, + "color": "#4f46e5", + "opacity": 0.1 + } + } +} +``` + +### Grouped links (only within same id) + +```json +{ + "particles": { + "groups": { + "teamA": { + "links": { "enable": true, "id": "teamA", "color": "#ff0000" } + }, + "teamB": { + "links": { "enable": true, "id": "teamB", "color": "#0000ff" } + } + } + } +} +``` ## Links Shadow -| key | option type | example | notes | -| -------- | ----------------------------- | ---------------- | -------------------------------------------------------------- | -| `blur` | `number` | `4` | | -| `color` | `string`
`color object` | | This `color` object is the same described here {@links IColor} | -| `enable` | `boolean` | `true` / `false` | | +Adds a blur glow effect to link lines. + +| Key | Type | Example | Notes | +| -------- | --------------------- | ---------------- | --------------------- | +| `enable` | `boolean` | `true` / `false` | Activates shadow | +| `blur` | `number` | `4` | Blur radius in pixels | +| `color` | string / color object | `"#ffffff"` | Shadow color | + +```json +{ + "links": { + "enable": true, + "shadow": { + "enable": true, + "blur": 5, + "color": "#00ffff" + } + } +} +``` ## Links Triangles -| key | option type | example | notes | -| --------- | ----------------------------- | ---------------- | -------------------------------------------------------------- | -| `color` | `string`
`color object` | | This `color` object is the same described here {@links IColor} | -| `enable` | `boolean` | `true` / `false` | | -| `opacity` | `number` | `0...1` | | +Fills triangles formed by three nearby linked particles. + +| Key | Type | Example | Notes | +| --------- | --------------------- | ---------------- | ----------------------- | +| `enable` | `boolean` | `true` / `false` | Activates triangle fill | +| `color` | string / color object | `"#ffffff"` | Triangle fill color | +| `opacity` | `number` | `0.1` | Fill opacity (0–1) | + +## Common pitfalls + +- Using `links` without loading a bundle that includes it (`@tsparticles/slim` or higher) +- Setting `distance` too low — with few particles spread across a large canvas, no links will appear +- Using `blink: true` and `consent: true` at the same time — `consent` takes precedence +- Setting `id` without configuring groups — standalone particles won't link at all + +## Related docs + +- Particles root: [Particles](../Particles.md) +- Color formats: [Color](../../Color.md) +- Options root: [Options](../../Options.md) diff --git a/markdown/Options/Particles/Move.md b/markdown/Options/Particles/Move.md index 88f1f64d8ba..3aee07b11b5 100644 --- a/markdown/Options/Particles/Move.md +++ b/markdown/Options/Particles/Move.md @@ -1,84 +1,210 @@ # Particles Move -| key | option type | example | notes | -| ----------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | -| `angle` | `object` | | See angle documentation below | -| `attract` | `object` | | See attract documentation below | -| `direction` | `string` | `"none"`
`"top"`
`"top-right"`
`"right"`
`"bottom-right"`
`"bottom"`
`"bottom-left"`
`"left"`
`"top-left"` | | -| `distance` | `object` | | See distance documentation below | -| `enable` | `boolean` | `true` / `false` | | -| `gravity` | `object` | | See gravity documentation below | -| `noise` | `object` | | See noise documentation below | -| `outModes` | `object` | | See out modes documentation below | -| `random` | `boolean` | `true` / `false` | | -| `size` | `boolean` | `true` / `false` | | -| `speed` | `number` | `4` | assuming a predefined distance for the particle to travel, `speed` is the amount of time takes to travel the predefined distance for any particle | -| `straight` | `boolean` | `true` / `false` | | -| `trail` | `object` | | See trail documentation below | -| `vibrate` | `boolean` | `true` / `false` | | -| `warp` | `boolean` | `true` / `false` | | +Controls how particles move across the canvas — direction, speed, gravity, noise, and boundary behavior. + +## Core properties + +| Key | Type | Example | Notes | +| ----------- | ------------------ | ----------------------------------- | ------------------------------------------------------------------------------------------ | +| `enable` | `boolean` | `true` / `false` | Activates movement | +| `speed` | `number` / `range` | `4` / `{ min: 1, max: 6 }` | Movement speed (relative units) | +| `direction` | `string` | `"none"` / `"top"` / `"bottom"` / … | Initial direction; full list below | +| `random` | `boolean` | `true` / `false` | Randomizes initial speed per particle | +| `straight` | `boolean` | `true` / `false` | When `true`, particles move in a fixed straight line | +| `vibrate` | `boolean` | `true` / `false` | Adds a vibration tremor effect | +| `warp` | `boolean` | `true` / `false` | Particles reappear on the opposite edge | +| `size` | `boolean` | `true` / `false` | Speed scales with particle size | +| `outModes` | `object` | | Behavior when particles reach canvas boundary — see [Out Modes](#particles-move-out-modes) | +| `angle` | `object` | | Spread angle offset — see [Angle](#particles-move-angle) | +| `attract` | `object` | | Attract toward a center point — see [Attract](#particles-move-attract) | +| `gravity` | `object` | | Gravity acceleration — see [Gravity](#particles-move-gravity) | +| `noise` | `object` | | Perlin/Simplex noise path — see [Noise](#particles-move-noise) | +| `trail` | `object` | | Trailing ghost effect — see [Trail](#particles-move-trail) | +| `spin` | `object` | | Spin around a center point — see [Spin](#particles-move-spin) | + +## Direction values + +`"none"` · `"top"` · `"top-right"` · `"right"` · `"bottom-right"` · `"bottom"` · `"bottom-left"` · `"left"` · `"top-left"` + +## Quick examples + +### Basic random movement + +```json +{ + "move": { + "enable": true, + "speed": 2 + } +} +``` + +### Falling particles (snow-like) + +```json +{ + "move": { + "enable": true, + "direction": "bottom", + "speed": 1.5, + "straight": false + } +} +``` + +### Rising particles (fire-like) with gravity off-screen destroy + +```json +{ + "move": { + "enable": true, + "direction": "top", + "speed": 3, + "outModes": { + "default": "destroy", + "bottom": "none" + } + } +} +``` + +### Gravity + bounce + +```json +{ + "move": { + "enable": true, + "gravity": { + "enable": true, + "acceleration": 9.81, + "maxSpeed": 50 + }, + "outModes": { + "default": "bounce", + "top": "none" + } + } +} +``` + +### Noise path (organic wandering) + +```json +{ + "move": { + "enable": true, + "noise": { + "enable": true, + "delay": { "value": 0 } + } + } +} +``` + +## Particles Move Out Modes + +Controls what happens when a particle exits the canvas boundary. + +| Value | Behavior | +| --------------------- | -------------------------------- | +| `"out"` | Wraps to the opposite side | +| `"destroy"` | Removes the particle | +| `"bounce"` | Bounces off the boundary | +| `"bounce-horizontal"` | Bounces only on horizontal edges | +| `"bounce-vertical"` | Bounces only on vertical edges | +| `"none"` | No special behavior | +| `"split"` | Splits the particle on exit | + +```json +{ + "outModes": { + "default": "out", + "top": "destroy", + "bottom": "bounce" + } +} +``` + +`default` applies to all sides not explicitly overridden. You can set `top`, `bottom`, `left`, `right` independently. ## Particles Move Angle -| key | option type | example | notes | -| -------- | ----------- | ---------------- | ----- | -| `offset` | `boolean` | `true` / `false` | | -| `value` | `number` | `3000` | | +Applies a spread offset angle to particle direction. -## Particles Move Attract +| Key | Type | Example | Notes | +| -------- | -------- | ------- | --------------------------------- | +| `value` | `number` | `90` | Spread angle in degrees | +| `offset` | `number` | `45` | Angular offset added to direction | -| key | option type | example | notes | -| ---------- | ----------- | ---------------- | ----- | -| `enable` | `boolean` | `true` / `false` | | -| `rotate.x` | `number` | `3000` | | -| `rotate.y` | `number` | `1500` | | +## Particles Move Attract -## Particles Move Distance +Pulls particles toward a virtual center defined by rotation axes. -| key | option type | example | notes | -| ------------ | ----------- | ------- | ----- | -| `horizontal` | `number` | `50` | | -| `vertical` | `number` | `50` | | +| Key | Type | Example | Notes | +| ---------- | --------- | ---------------- | ---------------------- | +| `enable` | `boolean` | `true` / `false` | Activates attract | +| `rotate.x` | `number` | `3000` | X-axis rotation factor | +| `rotate.y` | `number` | `1500` | Y-axis rotation factor | ## Particles Move Gravity -| key | option type | example | notes | -| -------------- | ----------- | ---------------- | ----- | -| `acceleration` | `number` | `9.81` | | -| `enable` | `boolean` | `true` / `false` | | -| `maxSpeed` | `number` | `50` | | +Simulates gravitational acceleration pulling particles downward. + +| Key | Type | Example | Notes | +| -------------- | --------- | ---------------- | -------------------------- | +| `enable` | `boolean` | `true` / `false` | Activates gravity | +| `acceleration` | `number` | `9.81` | Gravity acceleration value | +| `maxSpeed` | `number` | `50` | Caps falling speed | ## Particles Move Noise -| key | option type | example | notes | -| ------------- | ------------------- | ------------------------------ | ----- | -| `clamp` | `boolean` | `true` / `false` | | -| `delay.value` | `number` / `object` | `1` / `{ min: 0.5, max: 1.5 }` | | -| `enable` | `boolean` | `true` / `false` | | -| `generator` | `string` | `"generator name"` | | +Applies Perlin/Simplex noise for organic non-linear paths. -## Particles Move Out Modes - -| key | option type | example | notes | -| --------- | ----------- | ---------------------------------------------------------------------------- | ----- | -| `default` | `string` | `"out"`
`"destroy"`
`"bounce"`
`"none"`
`"split"` | | -| `bottom` | `string` | `"out"`
`"destroy"`
`"bounce"`
`"none"`
`"split"` | | -| `left` | `string` | `"out"`
`"destroy"`
`"bounce"`
`"none"`
`"split"` | | -| `right` | `string` | `"out"`
`"destroy"`
`"bounce"`
`"none"`
`"split"` | | -| `top` | `string` | `"out"`
`"destroy"`
`"bounce"`
`"none"`
`"split"` | | +| Key | Type | Example | Notes | +| ------------- | ------------------ | ------------------------------ | ---------------------------------- | +| `enable` | `boolean` | `true` / `false` | Activates noise movement | +| `delay.value` | `number` / `range` | `1` / `{ min: 0.5, max: 1.5 }` | Delay before noise kicks in | +| `clamp` | `boolean` | `true` / `false` | Clamps noise to canvas bounds | +| `generator` | `string` | `"simplexNoise"` | Name of the noise generator plugin | ## Particles Move Spin -| key | option type | example | notes | -| -------------- | ----------- | ------------------ | ----- | -| `acceleration` | `number` | `2` | | -| `enable` | `boolean` | `true` / `false` | | -| `position` | `object` | `{ x: 50, y: 50 }` | | +Rotates particles around a center point. + +| Key | Type | Example | Notes | +| -------------- | --------- | ---------------------- | --------------------------- | +| `enable` | `boolean` | `true` / `false` | Activates spin | +| `acceleration` | `number` | `2` | Angular acceleration | +| `position` | `object` | `{ "x": 50, "y": 50 }` | Center point as % of canvas | ## Particles Move Trail -| key | option type | example | notes | -| ----------- | -------------- | ---------------- | -------------------------------------------------------------- | -| `enable` | `boolean` | `true` / `false` | | -| `length` | `number` | `10` | | -| `fillColor` | `color object` | | This `color` object is the same described here {@links IColor} | +Renders a fading trail behind each particle. + +| Key | Type | Example | Notes | +| ----------- | --------------------- | ---------------- | ---------------------------- | +| `enable` | `boolean` | `true` / `false` | Activates trail | +| `length` | `number` | `10` | Number of trail frames | +| `fillColor` | color object / string | `"#000000"` | Color used to fade the trail | + +## Particles Move Distance + +Limits how far a particle can travel from its origin. + +| Key | Type | Example | Notes | +| ------------ | -------- | ------- | ------------------------------- | +| `horizontal` | `number` | `50` | Max horizontal travel in pixels | +| `vertical` | `number` | `50` | Max vertical travel in pixels | + +## Common pitfalls + +- Setting `enable: false` and expecting particles to animate — all movement is disabled +- Using `gravity` with `outModes: "out"` — particles will fall off the bottom and wrap to the top, which looks wrong; use `"destroy"` or `"bounce"` for gravity scenarios +- Enabling `noise` without loading the noise plugin +- Combining `straight: true` with a non-`"none"` noise generator — `straight` overrides noise + +## Related docs + +- Particles root: [Particles](../Particles.md) +- Out Modes: covered above +- Options root: [Options](../../Options.md) diff --git a/markdown/Options/Particles/Number.md b/markdown/Options/Particles/Number.md index 5c45b7201bd..3a8ab567d7c 100644 --- a/markdown/Options/Particles/Number.md +++ b/markdown/Options/Particles/Number.md @@ -1,8 +1,73 @@ # Particles Number -| key | option type | example | notes | -| ----------------------- | ----------- | ---------------- | ------------------------------ | -| `number.value` | `number` | `40` | | -| `number.limit` | `number` | `200` | `0` or less disables the limit | -| `number.density.enable` | `boolean` | `true` / `false` | | -| `number.density.area` | `number` | `800` | | +Controls how many particles exist and how their count is distributed across the canvas. + +## Properties + +| Key | Type | Example | Notes | +| ---------------- | --------- | ---------------- | --------------------------------------------------------- | +| `value` | `number` | `40` | Total particle count | +| `limit` | `number` | `200` | Maximum allowed particles; `0` or less disables the limit | +| `density.enable` | `boolean` | `true` / `false` | Scales particle count based on canvas area | +| `density.area` | `number` | `800` | Reference area (px²) used for density calculation | + +## Quick examples + +### Fixed count + +```json +{ + "number": { + "value": 60 + } +} +``` + +### Density-based count (adapts to screen size) + +```json +{ + "number": { + "value": 80, + "density": { + "enable": true, + "area": 800 + } + } +} +``` + +With `density.enable: true`, the actual particle count is calculated as: + +``` +count = value × (canvas area / area) +``` + +A `800×600` canvas with `value: 80` and `area: 800` will render approximately 60 particles. +A `1920×1080` canvas with the same config will render approximately 259 particles. + +### With a cap + +```json +{ + "number": { + "value": 80, + "limit": 150, + "density": { + "enable": true, + "area": 800 + } + } +} +``` + +## Common pitfalls + +- Setting a very high `value` without density enabled causes performance issues on small screens +- Setting `density.enable: true` but not adjusting `value` and `area` together leads to unexpected counts +- `limit` is a hard cap and applies after density calculation; if density produces a higher count, the excess is silently dropped + +## Related docs + +- Particles root: [Particles](../Particles.md) +- Options root: [Options](../../Options.md) diff --git a/markdown/Options/Particles/Opacity.md b/markdown/Options/Particles/Opacity.md index 4205193874c..a8f4222cb3b 100644 --- a/markdown/Options/Particles/Opacity.md +++ b/markdown/Options/Particles/Opacity.md @@ -1,10 +1,79 @@ # Particles Opacity -| key | option type | example | notes | -| ---------------------- | ------------------ | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `value` | `number` / `range` | `0...1` / `{ min: 0.1, max: 0.8 }` | | -| `animation.destroy` | `string` | `min`
`max`
`none` | Destroys the particles if not `none` when it reaches the `min` or `max`
value of the animation | -| `animation.enable` | `boolean` | `true` / `false` | | -| `animation.speed` | `number` | `3` | Rate expressed as % per second for particle opacity values to reach min and max
specified opacity values | -| `animation.startValue` | `string` | `min`
`max`
`random` | Defines where is the starting value of the animation, if `random` property
is set this will be ignored | -| `animation.sync` | `boolean` | `true` / `false` | Unless `animation.startValue` is set to `random`, when `sync` is toggled
`true`, particles will change opacity simultaneously for their entire
duration; when `false`, particles begin changing opacity from their
time of appearance, but independently of one another. | +Controls the transparency of particles, including animated fading effects. + +## Properties + +| Key | Type | Example | Notes | +| ---------------------- | ------------------ | -------------------------------- | ----------------------------------------------------------- | +| `value` | `number` / `range` | `0.5` / `{ min: 0.1, max: 0.8 }` | Base opacity (0–1) | +| `animation.enable` | `boolean` | `true` / `false` | Animates opacity over time | +| `animation.speed` | `number` | `3` | Rate of change (% per second toward min/max) | +| `animation.startValue` | `string` | `min` / `max` / `random` | Starting point of the animation | +| `animation.sync` | `boolean` | `true` / `false` | When `true`, all particles fade in sync | +| `animation.destroy` | `string` | `min` / `max` / `none` | Destroys the particle when opacity reaches the chosen bound | + +## Quick examples + +### Static opacity + +```json +{ + "opacity": { + "value": 0.5 + } +} +``` + +### Random opacity per particle + +```json +{ + "opacity": { + "value": { "min": 0.2, "max": 0.8 } + } +} +``` + +### Animated fade-in/out (twinkle-like effect) + +```json +{ + "opacity": { + "value": { "min": 0.1, "max": 1 }, + "animation": { + "enable": true, + "speed": 1, + "startValue": "random", + "sync": false + } + } +} +``` + +### Fade out and destroy + +```json +{ + "opacity": { + "value": 1, + "animation": { + "enable": true, + "speed": 0.5, + "startValue": "max", + "destroy": "min" + } + } +} +``` + +## Common pitfalls + +- Setting `animation.sync: true` with `startValue: random` — `sync` is ignored when `startValue` is `random` +- Using `destroy: "min"` without an emitter refilling particles leads to an empty canvas over time + +## Related docs + +- Particles root: [Particles](../Particles.md) +- Size (same animation shape): [Size](./Size.md) +- Options root: [Options](../../Options.md) diff --git a/markdown/Options/Particles/Orbit.md b/markdown/Options/Particles/Orbit.md index 7744ba23cea..fa9438fec52 100644 --- a/markdown/Options/Particles/Orbit.md +++ b/markdown/Options/Particles/Orbit.md @@ -1,12 +1,36 @@ # Particles Orbit -| key | option type | example | notes | -| ------------------ | ------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------- | -| `animation.enable` | `boolean` | `true` / `false` | | -| `animation.speed` | `number` | `0` | describes the rate of travel of a particle progressing along the
curve defined by other values in this property | -| `color` | `color object` | | This `color` object is the same described here {@links IColor} | -| `enable` | `object` | `true` / `false` | | -| `radius` | `number` | `0` | | -| `rotation.value` | `number` / `object` | `50` / `{ min: 10, max: 50 }` | | -| `opacity` | `number` | | | -| `width` | `number` | | | +Adds orbital movement around a center, optionally drawing visible orbit trails. + +## Properties + +| Key | Type | Example | Notes | +| ------------------ | ------------------ | ----------------------------- | ------------------------------------ | +| `enable` | `boolean` | `true` / `false` | Enables orbit behavior | +| `radius` | `number` | `0` | Orbit radius | +| `rotation.value` | `number` / `range` | `50` / `{ min: 10, max: 50 }` | Rotation amount | +| `animation.enable` | `boolean` | `true` / `false` | Enables orbit animation | +| `animation.speed` | `number` | `0` | Orbit animation speed | +| `color` | `color object` | | Orbit path color, see {@link IColor} | +| `opacity` | `number` | `0.5` | Orbit line opacity | +| `width` | `number` | `1` | Orbit line width | + +## Quick example + +```json +{ + "orbit": { + "enable": true, + "radius": 20, + "rotation": { + "value": { "min": 10, "max": 40 } + }, + "animation": { + "enable": true, + "speed": 2 + }, + "opacity": 0.3, + "width": 1 + } +} +``` diff --git a/markdown/Options/Particles/Repulse.md b/markdown/Options/Particles/Repulse.md index 4cfb302b2bb..bcfe8f52938 100644 --- a/markdown/Options/Particles/Repulse.md +++ b/markdown/Options/Particles/Repulse.md @@ -1,10 +1,29 @@ # Particles Repulse -| key | option type | example | notes | -| ---------- | ------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `enable` | `boolean` | `true` / `false` | | -| `distance` | `number` | `100` | | -| `duration` | `number` | `2` | | -| `factor` | `number` | `1` | | -| `speed` | `number` | `100` | The rate in seconds at which a particle will disperse
from around the cursor at any given time. A
`repulse` speed of `0` will result in no effect
on the particles. | -| `value` | `number` / `object` | `50` / `{ min: 10, max: 50 }` | | +Configures particle-to-particle repulsion behavior. + +## Properties + +| Key | Type | Example | Notes | +| ---------- | ------------------ | ----------------------------- | -------------------------- | +| `enable` | `boolean` | `true` / `false` | Enables repulse behavior | +| `distance` | `number` | `100` | Repulse distance | +| `duration` | `number` | `2` | Effect duration in seconds | +| `factor` | `number` | `1` | Repulse force multiplier | +| `speed` | `number` | `100` | Displacement speed | +| `value` | `number` / `range` | `50` / `{ min: 10, max: 50 }` | Base repulse intensity | + +## Quick example + +```json +{ + "repulse": { + "enable": true, + "distance": 120, + "duration": 1.5, + "factor": 1, + "speed": 80, + "value": { "min": 20, "max": 60 } + } +} +``` diff --git a/markdown/Options/Particles/Roll.md b/markdown/Options/Particles/Roll.md index 4eb10b6a53c..68c39345132 100644 --- a/markdown/Options/Particles/Roll.md +++ b/markdown/Options/Particles/Roll.md @@ -1,11 +1,34 @@ -# Particles Rotate - -| key | option type | example | notes | -| ------------------ | ------------------ | -------------------------- | --------------------------------------------------------------------------------------------------------------------- | -| `backColor` | `color object` | | This `color` object is the same described here {@links IColor} | -| `darken.enable` | `boolean` | `true` / `false` | | -| `darken.value` | `number` | `5` | The percent value subtracted to the particle fill color luminosity | -| `enable` | `boolean` | `true` / `false` | | -| `enlighten.enable` | `boolean` | `true` / `false` | | -| `enlighten.value` | `number` | `5` | The percent value added to the particle fill color luminosity | -| `speed` | `number` / `range` | `0` / `{ min: 1, max: 5 }` | Describes the rate of travel of a particle progressing along the
curve defined by other values in this property. | +# Particles Roll + +Adds a rolling effect that changes perceived front/back shading while particles move. + +## Properties + +| Key | Type | Example | Notes | +| ------------------ | ------------------ | -------------------------- | ----------------------------------- | +| `enable` | `boolean` | `true` / `false` | Enables roll effect | +| `speed` | `number` / `range` | `0` / `{ min: 1, max: 5 }` | Roll speed | +| `backColor` | `color object` | | Back-face color, see {@link IColor} | +| `darken.enable` | `boolean` | `true` / `false` | Enables darkening on rotation | +| `darken.value` | `number` | `5` | Percent of darkness | +| `enlighten.enable` | `boolean` | `true` / `false` | Enables lightening on rotation | +| `enlighten.value` | `number` | `5` | Percent of lightness | + +## Quick example + +```json +{ + "roll": { + "enable": true, + "speed": { "min": 2, "max": 6 }, + "darken": { + "enable": true, + "value": 15 + }, + "enlighten": { + "enable": false, + "value": 0 + } + } +} +``` diff --git a/markdown/Options/Particles/Rotate.md b/markdown/Options/Particles/Rotate.md index 728662b41f2..aa4931272b7 100644 --- a/markdown/Options/Particles/Rotate.md +++ b/markdown/Options/Particles/Rotate.md @@ -1,10 +1,31 @@ # Particles Rotate -| key | option type | example | notes | -| ------------------ | ------------------ | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `direction` | `string` | `"clockwise` / `counter-clockwise"` / `"random"` | | -| `path` | `boolean` | `true` / `false` | | -| `value` | `number` / `range` | `0` / `{ min: 90, max: 270 }` | angle in degrees | -| `animation.enable` | `boolean` | `true` / `false` | | -| `animation.speed` | `number` | `5` | Rate at which a particle turns expressed in degrees per second | -| `animation.sync` | `boolean` | `true` / `false` | When `sync` is toggled `true`, particles generated will rotate in
time with each other for their entire duration. However, when `sync` is
toggled `false`, particles generated begin turning at the set speed from
their time of appearance, but independently of one another. | +Controls particle rotation angle and rotation animation. + +## Properties + +| Key | Type | Example | Notes | +| ------------------ | ------------------ | -------------------------------------------------- | ------------------------------------ | +| `direction` | `string` | `"clockwise"` / `"counter-clockwise"` / `"random"` | Rotation direction | +| `path` | `boolean` | `true` / `false` | Rotates according to movement path | +| `value` | `number` / `range` | `0` / `{ min: 90, max: 270 }` | Base angle in degrees | +| `animation.enable` | `boolean` | `true` / `false` | Enables continuous rotation | +| `animation.speed` | `number` | `5` | Degrees per second | +| `animation.sync` | `boolean` | `true` / `false` | `true`: all particles rotate in sync | + +## Quick example + +```json +{ + "rotate": { + "value": { "min": 0, "max": 360 }, + "direction": "random", + "path": false, + "animation": { + "enable": true, + "speed": 25, + "sync": false + } + } +} +``` diff --git a/markdown/Options/Particles/Shadow.md b/markdown/Options/Particles/Shadow.md index c07fa943706..ec469c28dee 100644 --- a/markdown/Options/Particles/Shadow.md +++ b/markdown/Options/Particles/Shadow.md @@ -1,9 +1,31 @@ # Particles Shadow -| key | option type | example | notes | -| ---------- | -------------- | ---------------- | -------------------------------------------------------------- | -| `blur` | `number` | `4` | | -| `color` | `color object` | | This `color` object is the same described here {@links IColor} | -| `enable` | `boolean` | `true` / `false` | | -| `offset.x` | `number` | `10` | | -| `offset.y` | `number` | `10` | | +Adds a canvas shadow behind each particle. + +## Properties + +| Key | Type | Example | Notes | +| ---------- | -------------- | ---------------- | -------------------------------- | +| `enable` | `boolean` | `true` / `false` | Enables particle shadow | +| `blur` | `number` | `4` | Blur radius | +| `color` | `color object` | | Shadow color, see {@link IColor} | +| `offset.x` | `number` | `10` | Horizontal offset | +| `offset.y` | `number` | `10` | Vertical offset | + +## Quick example + +```json +{ + "shadow": { + "enable": true, + "blur": 8, + "color": { + "value": "#60a5fa" + }, + "offset": { + "x": 2, + "y": 2 + } + } +} +``` diff --git a/markdown/Options/Particles/Shape.md b/markdown/Options/Particles/Shape.md index 5eaad516ea6..a36bb7cb67f 100644 --- a/markdown/Options/Particles/Shape.md +++ b/markdown/Options/Particles/Shape.md @@ -1,44 +1,61 @@ # Shape -The Shape section of Particles options has been reworked a lot but for now it's still compatible with all your old -configurations. +Controls the visual shape of particles. Supports built-in shapes, images, emoji, and custom registered shapes. -If you want to customize more you particles you should use the new syntax +## Core properties -| key | option type | example | notes | -| --------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | -| `type` | `string`
`array` | `"circle"`
`"line"`
`"edge"`
`"triangle"`
`"polygon"`
`"star"`
`"image"`
`["circle", "triangle", "image"]` | | -| `options` | `object` | | This object is where new implementations are placed | +| Key | Type | Example | Notes | +| --------- | ------------------ | --------------------------------- | ------------------------------------------------------------------- | +| `type` | `string` / `array` | `"circle"` / `["circle", "star"]` | Shape type(s) to use; if array, one is picked randomly per particle | +| `options` | `object` | | Per-shape configuration — keys match shape type names | -## Shape Options +## Built-in shape types -Shape `options` is a dynamic object, is properties are the shape types, even the custom one you created (as you can read -above) and the values are objects or arrays that will be used to draw the particles. +| Value | Description | Bundle required | +| ------------------------ | ---------------------------- | -------------------- | +| `"circle"` | Filled circle | `@tsparticles/basic` | +| `"edge"` / `"square"` | Square | `@tsparticles/slim` | +| `"triangle"` | Triangle | `@tsparticles/slim` | +| `"polygon"` | Regular polygon with N sides | `@tsparticles/slim` | +| `"star"` | Star with N points | `@tsparticles/slim` | +| `"line"` | Straight line | `@tsparticles/slim` | +| `"image"` / `"images"` | External image or SVG | `@tsparticles/slim` | +| `"character"` / `"char"` | Text / emoji character | `@tsparticles/slim` | -This will give us more customization, you can now specify a shape type with a `particles` property that lets you -customize almost all the properties of the original object. +## Quick examples -`shape` and `number` will be ignored for obvious reasons. +### Circle (default) -The shape types you find described above are the only implemented here, if you use an external custom shape ask the -creator. - -All the shapes have in common these properties +```json +{ + "shape": { + "type": "circle" + } +} +``` -| key | option type | example | notes | -| ----------- | ----------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------- | -| `particles` | `object` | | See Particles options [here](https://particles.js.org/docs/interfaces/_options_interfaces_ioptions_.ioptions.html-Particles) | -| `fill` | `boolean` | `true` / `false` | Used to specify if its shape particles should be filled with color or not | -| `close` | `boolean` | `true` / `false` | Used to specify if its shape particles should have a closed shape | +### Random mix of shapes -Below you'll find the options of some shape types that need additional properties, you can add to the object below the 3 -properties above. +```json +{ + "shape": { + "type": ["circle", "triangle", "star"] + } +} +``` -### Polygon +### Polygon (hexagon) -```javascript -polygon: { - sides: 5; // the number of sides of the polygon +```json +{ + "shape": { + "type": "polygon", + "options": { + "polygon": { + "sides": 6 + } + } + } } ``` @@ -46,22 +63,32 @@ polygon: { ```json { - "star": { - "sides": 5, // the number of sides of the star - "inset": 2 // the inset length, 2 is the default and an acceptable value + "shape": { + "type": "star", + "options": { + "star": { + "sides": 5, + "inset": 2 + } + } } } ``` -### Character / Char +### Emoji particles ```json { - "character": { - "value": "*", // the text to use as particles, any string is valid, for escaping unicode char use the `\uXXXX` syntax - "font": "Verdana", // the font to use to draw the text. If the font needs an external css or javascript like FontAwesome you should include all the necessary files on your own - "style": "", // any additional css style to add to the text - "weight": "" // the css weight property, some fonts like font awesome have a specified weight, check the documentation if needed + "shape": { + "type": "character", + "options": { + "character": { + "value": ["❄️", "⛄", "🌨️"], + "font": "Segoe UI Emoji", + "style": "", + "weight": "400" + } + } } } ``` @@ -70,15 +97,61 @@ polygon: { ```json { - "image": { - // any path or url to your image that will be used as a particle - "src": "http://mywebsite.com/assets/img/image.png", - // the pixel width of the image, you can use any value, the image will be scaled - "width": 100, - // the pixel height of the image, you can use any value, the image will be scaled - "height": 100, - // if true and the image type is SVG, it will replace all the colors with the particle color - "replaceColor": false + "shape": { + "type": "image", + "options": { + "image": { + "src": "https://example.com/logo.png", + "width": 32, + "height": 32, + "replaceColor": false + } + } } } ``` + +Set `replaceColor: true` for SVG images to tint them with the particle `color`. + +### Custom registered shape + +```javascript +tsParticles.addShape("myShape", drawer); +``` + +```json +{ + "shape": { + "type": "myShape", + "options": { + "myShape": { + "close": true, + "fill": true + } + } + } +} +``` + +## Shape options common properties + +All shape types accept these properties inside their `options` object: + +| Key | Type | Notes | +| ----------- | --------- | ------------------------------------------------------------ | +| `fill` | `boolean` | Fill the shape with color | +| `close` | `boolean` | Close the shape path | +| `particles` | `object` | Per-shape particle overrides (see {@link IParticlesOptions}) | + +## Common pitfalls + +- Using `"square"` or `"triangle"` with `@tsparticles/basic` — these shapes require `@tsparticles/slim` or the dedicated shape package +- Using `"image"` without providing `width` and `height` — the image may render at unexpected sizes +- Using `"character"` with an emoji that relies on an external font without including that font in the page +- Using `replaceColor: true` on raster images (PNG/JPG) — only works with SVG + +## Related docs + +- Particles root: [Particles](../Particles.md) +- Custom shapes (plugins): [Plugins](../../Plugins.md) +- Options root: [Options](../../Options.md) diff --git a/markdown/Options/Particles/Size.md b/markdown/Options/Particles/Size.md index eed62033adb..525d032c094 100644 --- a/markdown/Options/Particles/Size.md +++ b/markdown/Options/Particles/Size.md @@ -1,10 +1,80 @@ # Particles Size -| key | option type | example | notes | -| ---------------------- | ------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `value` | `number` / `object` | `50` / `{ min: 10, max: 50 }` | | -| `animation.destroy` | `string` | `min`
`max`
`none` | Destroys the particles if not `none` when it reaches the `min` or
`max` value of the animation | -| `animation.enable` | `boolean` | `true` / `false` | | -| `animation.speed` | `number` | `3` | Describes the rate at which particles will shrink or grow as a
function of other `size` values | -| `animation.startValue` | `string` | `min`
`max`
`random` | Defines where is the starting value of the animation, if `random`
property is set this will be ignored | -| `animation.sync` | `boolean` | `true` / `false` | Unless `animation.startValue` is set to `random`, when `sync` is
toggled `true`, particles will change size simultaneously for
their entire duration; when `false`, particles begin changing
size from their time of appearance, but independently
of one another. | +Controls the visual size of particles, including animated grow/shrink effects. + +## Properties + +| Key | Type | Example | Notes | +| ---------------------- | ------------------ | -------------------------- | -------------------------------------------------------- | +| `value` | `number` / `range` | `4` / `{ min: 1, max: 8 }` | Base radius in pixels | +| `animation.enable` | `boolean` | `true` / `false` | Animates size over time | +| `animation.speed` | `number` | `3` | Rate of change as a function of other size values | +| `animation.startValue` | `string` | `min` / `max` / `random` | Starting point of the animation | +| `animation.sync` | `boolean` | `true` / `false` | When `true`, all particles resize in sync | +| `animation.destroy` | `string` | `min` / `max` / `none` | Destroys the particle when size reaches the chosen bound | + +## Quick examples + +### Fixed size + +```json +{ + "size": { + "value": 4 + } +} +``` + +### Random size per particle + +```json +{ + "size": { + "value": { "min": 1, "max": 6 } + } +} +``` + +### Pulsing effect (grow and shrink) + +```json +{ + "size": { + "value": { "min": 2, "max": 8 }, + "animation": { + "enable": true, + "speed": 2, + "startValue": "random", + "sync": false + } + } +} +``` + +### Shrink to destruction (e.g. for emitter-based effects) + +```json +{ + "size": { + "value": 6, + "animation": { + "enable": true, + "speed": 1, + "startValue": "max", + "destroy": "min" + } + } +} +``` + +## Common pitfalls + +- Using `destroy: "min"` without an emitter to replenish particles will result in an empty canvas +- `animation.sync: true` is ignored when `startValue` is `random` +- Retina devices multiply `value` by `devicePixelRatio`; combine with `detectRetina: true` for consistent results + +## Related docs + +- Particles root: [Particles](../Particles.md) +- Opacity (same animation shape): [Opacity](./Opacity.md) +- Options root: [Options](../../Options.md) diff --git a/markdown/Options/Particles/Stroke.md b/markdown/Options/Particles/Stroke.md index c7bc1dd4085..e2728cd1bd3 100644 --- a/markdown/Options/Particles/Stroke.md +++ b/markdown/Options/Particles/Stroke.md @@ -1,6 +1,23 @@ # Particles Stroke -| key | option type | example | notes | -| ------- | -------------- | ------- | ----------------------------------------------------------------------- | -| `width` | `number` | `2` | | -| `color` | `color object` | | This `color` object is the same described here {@link IAnimatableColor} | +Defines the outline drawn around particle shapes. + +## Properties + +| Key | Type | Example | Notes | +| ------- | -------------- | ------- | ------------------------------------------ | +| `width` | `number` | `2` | Stroke width in pixels | +| `color` | `color object` | | Stroke color, see {@link IAnimatableColor} | + +## Quick example + +```json +{ + "stroke": { + "width": 2, + "color": { + "value": "#ffffff" + } + } +} +``` diff --git a/markdown/Options/Particles/Tilt.md b/markdown/Options/Particles/Tilt.md index ee829ec1958..684a394f710 100644 --- a/markdown/Options/Particles/Tilt.md +++ b/markdown/Options/Particles/Tilt.md @@ -1,10 +1,31 @@ # Particles Tilt -| key | option type | example | notes | -| ------------------ | ------------------ | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `enable` | `boolean` | `true` / `false` | | -| `value` | `number` / `range` | `0` / `{ min: 1, max: 5 }` | angle in degrees | -| `direction` | `string` | `"clockwise"` / `"counter-clockwise"` / `"random"` | | -| `animation.enable` | `boolean` | `true` / `false` | | -| `animation.speed` | `number` | `5` | Describes the rate at which a particle will turn as a function
of `value` inputs | -| `animation.sync` | `boolean` | `true` / `false` | When `sync` is toggled `true`, particles generated will turn in
time with each other for their entire duration. However, when `sync` is
toggled `false`, particles generated begin turning at the set speed from
their time of appearance, but independently of one another. | +Applies tilt rotation to particle rendering. + +## Properties + +| Key | Type | Example | Notes | +| ------------------ | ------------------ | -------------------------------------------------- | ----------------------------------- | +| `enable` | `boolean` | `true` / `false` | Enables tilt effect | +| `value` | `number` / `range` | `0` / `{ min: 1, max: 5 }` | Base tilt angle in degrees | +| `direction` | `string` | `"clockwise"` / `"counter-clockwise"` / `"random"` | Tilt direction | +| `animation.enable` | `boolean` | `true` / `false` | Enables tilt animation | +| `animation.speed` | `number` | `5` | Tilt speed | +| `animation.sync` | `boolean` | `true` / `false` | `true`: synchronized tilt animation | + +## Quick example + +```json +{ + "tilt": { + "enable": true, + "value": { "min": 0, "max": 45 }, + "direction": "random", + "animation": { + "enable": true, + "speed": 20, + "sync": false + } + } +} +``` diff --git a/markdown/Options/Particles/Twinkle.md b/markdown/Options/Particles/Twinkle.md index de559c8d402..c5153f42a58 100644 --- a/markdown/Options/Particles/Twinkle.md +++ b/markdown/Options/Particles/Twinkle.md @@ -1,9 +1,33 @@ # Particles Twinkle -| key | option type | example | notes | -| --------------------- | -------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------ | -| `particles.enable` | `boolean` | `true` / `false` | | -| `particles.color` | `color object` | | This `color` object is the same described here {@link IColor}, this value is optional | -| `particles.frequency` | `number` | `0...1` | This value will be the comparison to `Math.random()` call, if the random value is greater the twinkle effect will be displayed | -| `particles.opacity` | `number` | `0...1` | | -| `lines` | `object` | | The same values of `particles` but applied to linked lines | +Adds random blinking effects to particles and links. + +## Properties + +| Key | Type | Example | Notes | +| --------------------- | -------------- | ---------------- | ------------------------------------------------ | +| `particles.enable` | `boolean` | `true` / `false` | Enables particle twinkle | +| `particles.color` | `color object` | | Optional twinkle color, see {@link IColor} | +| `particles.frequency` | `number` | `0...1` | Probability threshold for twinkle per frame | +| `particles.opacity` | `number` | `0...1` | Twinkle opacity | +| `lines` | `object` | | Same properties as `particles`, applied to links | + +## Quick example + +```json +{ + "twinkle": { + "particles": { + "enable": true, + "frequency": 0.05, + "opacity": 1, + "color": { + "value": "#ffffff" + } + }, + "lines": { + "enable": false + } + } +} +``` diff --git a/markdown/Options/Particles/Wobble.md b/markdown/Options/Particles/Wobble.md index 5990216196a..2f65d8c85bd 100644 --- a/markdown/Options/Particles/Wobble.md +++ b/markdown/Options/Particles/Wobble.md @@ -1,7 +1,29 @@ # Particles Wobble -| key | option type | example | notes | -| ---------- | ------------------ | -------------------------- | --------------------------------------------------------------------------------------------------------------------- | -| `distance` | `number` / `range` | `0` / `{ min: 1, max: 5 }` | | -| `enable` | `boolean` | `true` / `false` | | -| `speed` | `number` / `range` | `0` / `{ min: 1, max: 5 }` | Describes the rate of travel of a particle progressing along the
curve defined by other values in this property. | +Applies oscillating movement on top of normal particle motion. + +## Properties + +| Key | Type | Example | Notes | +| ---------- | ------------------ | -------------------------- | --------------------- | +| `enable` | `boolean` | `true` / `false` | Enables wobble effect | +| `distance` | `number` / `range` | `0` / `{ min: 1, max: 5 }` | Oscillation amplitude | +| `speed` | `number` / `range` | `0` / `{ min: 1, max: 5 }` | Oscillation speed | + +## Quick example + +```json +{ + "wobble": { + "enable": true, + "distance": { + "min": 2, + "max": 6 + }, + "speed": { + "min": 4, + "max": 10 + } + } +} +``` diff --git a/markdown/Options/Particles/ZIndex.md b/markdown/Options/Particles/ZIndex.md index 1ca57f8c957..b6d2331329c 100644 --- a/markdown/Options/Particles/ZIndex.md +++ b/markdown/Options/Particles/ZIndex.md @@ -1,8 +1,28 @@ # Particles zIndex -| key | option type | example | notes | -| -------------- | ------------------- | ---------------------------------- | --------------------------------------------------------------- | -| `value` | `number` / `object` | `0...100` / `{ min: 0, max: 100 }` | Defaults to 0. | -| `opacityRate` | `number` | `2` | The rate with which the z-index alters the particle's opacity. | -| `velocityRate` | `number` | `-10` | The rate with which the z-index alters the particle's velocity. | -| `sizeRate` | `number` | `5` | The rate with which the z-index alters the particle's size. | +Controls how particle layering affects opacity, velocity, and size. + +## Properties + +| Key | Type | Example | Notes | +| -------------- | ------------------ | ---------------------------------- | ---------------------------------------- | +| `value` | `number` / `range` | `0...100` / `{ min: 0, max: 100 }` | Base z-layer value | +| `opacityRate` | `number` | `2` | Multiplier applied to opacity by zIndex | +| `velocityRate` | `number` | `-10` | Multiplier applied to velocity by zIndex | +| `sizeRate` | `number` | `5` | Multiplier applied to size by zIndex | + +## Quick example + +```json +{ + "zIndex": { + "value": { + "min": 0, + "max": 50 + }, + "opacityRate": 1, + "velocityRate": -2, + "sizeRate": 2 + } +} +``` diff --git a/markdown/Options/Plugins/Absorbers.md b/markdown/Options/Plugins/Absorbers.md index 00495e0bc03..d6e531ce39f 100644 --- a/markdown/Options/Plugins/Absorbers.md +++ b/markdown/Options/Plugins/Absorbers.md @@ -1,10 +1,36 @@ # Absorbers -| key | option type | example | notes | -| -------------- | ------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------- | -| `color` | `color object` | | This `color` object is the same described here {@link IColor} | -| `opacity` | `number` | `0...1` | | -| `position` | `object` | `{ "x": 50, "y": 50 }` | The position specified is not absolute, it will be used as a percent value of the canvas size. | -| `size.density` | `number` | `5` | The higher the value, the more the particles are attracted | -| `size.limit` | `number` | `100` | The absorber max radius, this value is optional | -| `size.value` | `number` / `object` | `50` / `{ min: 10, max: 50 }` | The absorber radius | +Defines absorber entities that pull nearby particles and can consume them. + +## Properties + +| Key | Type | Example | Notes | +| -------------- | ------------------ | ----------------------------- | ---------------------------------- | +| `color` | `color object` | | Absorber color, see {@link IColor} | +| `opacity` | `number` | `0...1` | Absorber opacity | +| `position` | `object` | `{ "x": 50, "y": 50 }` | Position in canvas percent values | +| `size.value` | `number` / `range` | `50` / `{ min: 10, max: 50 }` | Absorber radius | +| `size.density` | `number` | `5` | Attraction intensity | +| `size.limit` | `number` | `100` | Maximum absorber radius | + +## Quick example + +```json +{ + "absorbers": { + "color": { + "value": "#f59e0b" + }, + "opacity": 0.7, + "position": { + "x": 50, + "y": 50 + }, + "size": { + "value": 30, + "density": 6, + "limit": 120 + } + } +} +``` diff --git a/markdown/Options/Plugins/Emitters.md b/markdown/Options/Plugins/Emitters.md index b30cdbcac34..9ecf5227905 100644 --- a/markdown/Options/Plugins/Emitters.md +++ b/markdown/Options/Plugins/Emitters.md @@ -1,15 +1,47 @@ # Emitters -| key | option type | example | notes | -| --------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | -| `direction` | `string` | `"none"`
`"top"`
`"top-right"`
`"right"`
`"bottom-right"`
`"bottom"`
`"bottom-left"`
`"left"`
`"top-left"` | The generated particles direction | -| `life.count` | `number` | `1` | The emitter number of times will appear | -| `life.duration` | `number` | `5` | The emitter life duration, in seconds | -| `life.delay` | `number` | `0.1` | The emitter delay between any appearance | -| `particles` | `object` | | See Particles options here {@link IParticlesOptions} | -| `position` | `object` | `{ "x": 50, "y": 50 }` | The position specified is not absolute, it will be used as a percent value of the canvas size. | -| `size.width` | `number` | `10` | | -| `size.height` | `number` | `10` | | -| `size.mode` | `string` | `"precise"` / `"percent"` | Specify how to use the size values, `precise` uses pixels, `percent` will be calculated on canvas size | -| `rate.quantity` | `number` | `1` | The particles generated everytime the rate event occurs | -| `rate.delay` | `number` | `0.1` | The rate event event delay time, in seconds | +Defines particle emitters that continuously or periodically spawn particles. + +## Properties + +| Key | Type | Example | Notes | +| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- | +| `direction` | `string` | `"none"`, `"top"`, `"top-right"`, `"right"`, `"bottom-right"`, `"bottom"`, `"bottom-left"`, `"left"`, `"top-left"` | Spawn direction | +| `life.count` | `number` | `1` | Number of emitter cycles | +| `life.duration` | `number` | `5` | Emitter active duration (seconds) | +| `life.delay` | `number` | `0.1` | Delay between cycles (seconds) | +| `particles` | `object` | | Spawned particle options, see {@link IParticlesOptions} | +| `position` | `object` | `{ "x": 50, "y": 50 }` | Position in canvas percent values | +| `size.width` | `number` | `10` | Emitter area width | +| `size.height` | `number` | `10` | Emitter area height | +| `size.mode` | `string` | `"precise"` / `"percent"` | `precise`: pixels, `percent`: relative to canvas size | +| `rate.quantity` | `number` | `1` | Particles generated per emission | +| `rate.delay` | `number` | `0.1` | Delay between emissions (seconds) | + +## Quick example + +```json +{ + "emitters": { + "direction": "top", + "position": { + "x": 50, + "y": 90 + }, + "size": { + "width": 40, + "height": 0, + "mode": "percent" + }, + "rate": { + "quantity": 4, + "delay": 0.15 + }, + "particles": { + "move": { + "speed": 2 + } + } + } +} +``` diff --git a/markdown/Options/Plugins/Infection.md b/markdown/Options/Plugins/Infection.md index 02076fccdf4..d341cb1f6b6 100644 --- a/markdown/Options/Plugins/Infection.md +++ b/markdown/Options/Plugins/Infection.md @@ -1,19 +1,47 @@ # Infection -| key | option type | example | notes | -| ------------ | ----------- | ---------------- | ----------------------------------------------------------------------------------- | -| `cure` | `boolean` | `true` / `false` | if the infection can be cured, bringing back the particle to its normal state | -| `delay` | `number` | `1` | the "symptoms" delay, after how many seconds the infected particle change its state | -| `enable` | `boolean` | `true` / `false` | | -| `infections` | `number` | `1` | how many particles are infected at startup | -| `stages` | `array` | | | +Configures infection-like propagation between particles. -## Infection Stage +## Properties -| key | option type | example | notes | -| --------------- | -------------- | ------- | ----------------------------------------------------------------------------------- | -| `color` | `color object` | | This `color` object is the same described here {@link IColor} | -| `radius` | `number` | `1` | an outer radius for spreading the infection without touch | -| `rate` | `number` | `1` | chances of infecting other particles | -| `duration` | `number` | `1` | how many seconds does the stage should last | -| `infectedStage` | `number` | `0` | which stage should be set when a particle will be infected by another at this stage | +| Key | Type | Example | Notes | +| ------------ | --------- | ---------------- | --------------------------------------- | +| `enable` | `boolean` | `true` / `false` | Enables infection mode | +| `infections` | `number` | `1` | Number of particles infected at startup | +| `delay` | `number` | `1` | Delay in seconds before symptoms apply | +| `cure` | `boolean` | `true` / `false` | If infected particles can recover | +| `stages` | `array` | | Infection stages sequence | + +## Infection stage properties + +| Key | Type | Example | Notes | +| --------------- | -------------- | ------- | --------------------------------------- | +| `color` | `color object` | | Stage color, see {@link IColor} | +| `radius` | `number` | `1` | Infection spread radius | +| `rate` | `number` | `1` | Infection chance multiplier | +| `duration` | `number` | `1` | Stage duration in seconds | +| `infectedStage` | `number` | `0` | Next stage index for infected particles | + +## Quick example + +```json +{ + "infection": { + "enable": true, + "infections": 2, + "delay": 0.5, + "cure": true, + "stages": [ + { + "color": { + "value": "#22c55e" + }, + "radius": 1, + "rate": 0.3, + "duration": 2, + "infectedStage": 0 + } + ] + } +} +``` diff --git a/markdown/Options/Plugins/PolygonMask.md b/markdown/Options/Plugins/PolygonMask.md index 0cb25f893a7..932771f999f 100644 --- a/markdown/Options/Plugins/PolygonMask.md +++ b/markdown/Options/Plugins/PolygonMask.md @@ -1,13 +1,44 @@ # Polygon Mask -| key | option type | example | notes | -| ---------------- | -------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | --- | -| `enable` | `boolean` | `true` / `false` | | -| `draw.enable` | `boolean` | `true` / `false` | | -| `draw.lineWidth` | `number` | `0.5` | | -| `draw.lineColor` | `color object` | | This `color` object is the same described here {@link IColor} | | -| `position` | `object` | `{ "x": 50, "y": 50 }` | The position specified is not absolute, it will be used as a percent value. | -| `scale` | `number` | 1 | | -| `type` | `string` | `none`
`inside`
`outside`
`inline` | | -| `move.radius` | `number` | `10` | | -| `url` | `string` | `demo/svg/deer.svg` | this file will be downloaded with an ajax request, if it won't load you have some **XSS** issues | +Constrains particles to a polygon/SVG shape and optionally draws its outline. + +## Properties + +| Key | Type | Example | Notes | +| ---------------- | -------------- | --------------------------------------------- | ---------------------------------- | +| `enable` | `boolean` | `true` / `false` | Enables polygon mask | +| `url` | `string` | `"demo/svg/deer.svg"` | SVG source URL | +| `type` | `string` | `"none"`, `"inside"`, `"outside"`, `"inline"` | Particle placement mode | +| `position` | `object` | `{ "x": 50, "y": 50 }` | Position in canvas percent values | +| `scale` | `number` | `1` | Polygon scale factor | +| `move.radius` | `number` | `10` | Movement radius along inline paths | +| `draw.enable` | `boolean` | `true` / `false` | Draws polygon outline | +| `draw.lineWidth` | `number` | `0.5` | Outline width | +| `draw.lineColor` | `color object` | | Outline color, see {@link IColor} | + +## Quick example + +```json +{ + "polygon": { + "enable": true, + "url": "demo/svg/deer.svg", + "type": "inline", + "position": { + "x": 50, + "y": 50 + }, + "scale": 1, + "move": { + "radius": 8 + }, + "draw": { + "enable": false, + "lineWidth": 0.5, + "lineColor": { + "value": "#ffffff" + } + } + } +} +``` diff --git a/markdown/Options/Themes.md b/markdown/Options/Themes.md index 397fd025f95..cdba47454e6 100644 --- a/markdown/Options/Themes.md +++ b/markdown/Options/Themes.md @@ -1,33 +1,87 @@ # Theme Options -- [Theme Options](#theme-options) - - [Default](#default) - - [Mode](#mode) - - [Value](#value) - - [Name](#name) - - [Options](#options) +Allows defining multiple named themes (light/dark/any) that can be switched at runtime via `container.loadTheme(name)`. -## Default +## Structure -- [mode](#mode) -- [value](#value) +```json +{ + "themes": [ + { + "name": "dark", + "default": { + "value": true, + "mode": "dark" + }, + "options": { + "background": { "color": "#0d1117" }, + "particles": { "color": { "value": "#ffffff" } } + } + }, + { + "name": "light", + "default": { + "value": true, + "mode": "light" + }, + "options": { + "background": { "color": "#ffffff" }, + "particles": { "color": { "value": "#000000" } } + } + } + ] +} +``` -### Mode +## Properties -Values accepted +### `name` -- `"any"` -- `"dark"` -- `"light"` +A string identifier used to reference the theme in `container.loadTheme("dark")`. -### Value +### `default` -If set to `true` this theme will be the default one for the specified mode, the last one set to default will be used if more than one are set. +Controls whether and when this theme is applied automatically. -## Name +| Key | Type | Values | Notes | +| --------------- | --------- | ------------------------------ | ------------------------------------------------------- | +| `default.value` | `boolean` | `true` / `false` | If `true`, this is the default theme for the given mode | +| `default.mode` | `string` | `"any"` / `"dark"` / `"light"` | Applies when the OS/browser reports this color scheme | -The theme name used to change the theme using the {@link Container.loadTheme} function +- `"dark"` — applied when `prefers-color-scheme: dark` is detected +- `"light"` — applied when `prefers-color-scheme: light` is detected +- `"any"` — applied regardless of system preference -## Options +If more than one theme sets `default.value: true` for the same `mode`, the last one wins. -This object is the entire {@link Options | options } object +### `options` + +A partial {@link Options} object. Only the properties you specify will override the base config — everything else remains unchanged. + +## Switching themes at runtime + +```javascript +const container = await tsParticles.load({ + id: "tsparticles", + options: { + /* ... */ + }, +}); + +// Switch to a named theme +container.loadTheme("dark"); + +// Reset to the default theme for the current mode +container.loadTheme(undefined); +``` + +## Common pitfalls + +- Defining two themes with `default.value: true` for the same `mode` — only the last one is used +- Passing a `name` that was not registered in `themes` to `loadTheme()` — nothing changes +- Setting complex nested overrides in `options` and expecting deep merge — only specified keys are overridden + +## Related docs + +- Container runtime API: [Container](../Container.md) +- Options root: [Options](../Options.md) diff --git a/markdown/Pages/index.md b/markdown/Pages/index.md index 3a7845af0e0..0c942001bc9 100644 --- a/markdown/Pages/index.md +++ b/markdown/Pages/index.md @@ -1,3 +1,129 @@ # tsParticles -## Index Page +Quick guide to choose the right package, find the right option reference, and start from presets, palettes, or ready-made configs in a few minutes. + +## Quick checklist + +If this is your first time with tsParticles: + +1. Install `@tsparticles/engine` +2. Pick one runtime path: + - `@tsparticles/slim` for most production websites and apps + - `@tsparticles/all` for prototypes, playgrounds, and full feature coverage + - only the packages you need if you want a minimal custom build +3. Load your chosen bundle once +4. Start with one of these inputs: + - manual options + - a ready-made config from `@tsparticles/configs` + - an official preset from the `tsparticles/presets` repository + +## Minimal start example + +```ts +import { tsParticles } from "@tsparticles/engine"; +import { loadSlim } from "@tsparticles/slim"; + +await loadSlim(tsParticles); + +await tsParticles.load({ + id: "tsparticles", + options: { + background: { + color: "#0d1117", + }, + particles: { + number: { + value: 60, + }, + move: { + enable: true, + speed: 1.2, + }, + size: { + value: { min: 1, max: 3 }, + }, + }, + }, +}); +``` + +## Choose your quick-start path + +- **I need a production-ready default**: `@tsparticles/slim` +- **I need only core plus custom plugins**: `@tsparticles/engine` +- **I need every feature for quick prototyping**: `@tsparticles/all` +- **I want a ready visual starting point**: use `@tsparticles/configs` or an official preset first + +## Quick documentation map + +- Root options: [Options](../Options.md) +- Color formats and values: [Color](../Color.md) +- Runtime container management: [Container](../Container.md) +- Plugins, custom shapes, custom presets: [Plugins](../Plugins.md) +- Migration from particles.js: [pjsMigration](../pjsMigration.md) + +## Detailed option guides + +- Canvas and global behavior: [Background](../Options/Background.md), [Background Mask](../Options/BackgroundMask.md), [Full Screen](../Options/FullScreen.md), [Motion](../Options/Motion.md) +- Interactivity: [Interactivity](../Options/Interactivity.md), [Click](../Options/Interactivity/Click.md), [Hover](../Options/Interactivity/Hover.md), [Div](../Options/Interactivity/Div.md) +- Particle behavior: [Particles](../Options/Particles.md), [Color](../Options/Particles/Color.md), [Collisions](../Options/Particles/Collisions.md), [Life](../Options/Particles/Life.md), [Orbit](../Options/Particles/Orbit.md) +- Plugin-driven options: [Absorbers](../Options/Plugins/Absorbers.md), [Emitters](../Options/Plugins/Emitters.md), [Infection](../Options/Plugins/Infection.md), [Polygon Mask](../Options/Plugins/PolygonMask.md) + +## Ready-made starting sources + +### Configs (`@tsparticles/configs`) + +Use configs when you want a concrete example object you can inspect and modify directly. + +- Package README:
+- Typical use case: copy a working config, then tune particles, interactivity, and visuals step by step
+
+### Presets
+
+Use presets when you want a reusable effect name such as `stars`, `fireworks`, or `confetti`.
+
+- Repository:
+- Demo catalog:
+- Palette-based demos:
+- Official palettes:
+- Demo configs:
+- Root options: [Options](./Options.md)
+- Docs introduction: [Pages/index](./Pages/index.md)
diff --git a/markdown/pjsMigration.md b/markdown/pjsMigration.md
index 29fded728d7..2f8ea217049 100644
--- a/markdown/pjsMigration.md
+++ b/markdown/pjsMigration.md
@@ -1,89 +1,72 @@
# Migrating from Particles.js
-tsParticles is fully compatible with Particles.js and the migration is really easy to do.
+tsParticles is compatible with particles.js, and migration can be done in a few steps.
-Let's checkout your possible HTML code.
+## Quick checklist
-## Simple solution
+1. Replace `particles.min.js` with `tsparticles.min.js`
+2. Update canvas CSS class names (`particles-js` -> `tsparticles`)
+3. Replace `particlesJS(...)` APIs with `tsParticles.load(...)`
+4. Gradually migrate deprecated options (`snake_case` -> `camelCase`)
-You should have something like the following code
+## 1) Migrate script and CSS
```html
```
-Well to migrate from particles.js to tsParticles all you have to do is replace that to this
+becomes:
```html
```
-If you have customized the css like this:
+If you had custom CSS on the canvas:
```css
.particles-js-canvas-element {
- /* your awesome CSS code */
+ /* custom CSS */
}
```
-You have to change it like this
+becomes:
```css
.tsparticles-canvas-element {
- /* your awesome CSS code */
+ /* custom CSS */
}
```
-And you're done. Easy isn't it?
+## 2) Migrate JavaScript API
-## Advanced solution
+### Quick mapping
-Probably you noticed some warnings in the console. Well yes, it's really easy doing the migration but new features requires new configs and bug fixes can mess up some things.
+| particles.js | tsParticles |
+| ------------------------------------------ | ---------------------------------------------- |
+| `particlesJS("id", options)` | `tsParticles.load({ id: "id", options })` |
+| `particlesJS.load("id", "path", callback)` | `tsParticles.loadJSON("id", "path").then(...)` |
-If you're not familiar with Javascript don't worry, you can skip this part and keep the warnings, everything will work fine.
+### Practical example
-If you care about console warnings well you are in the right place.
+Before:
-The particlesJS identifier is now obsolete, well the library has a new name so it changed.
-
-Now let's checkout the Javascript code, you should have something like this
-
-```javascript
-/* particlesJS.load(@dom-id, @path-json, @callback (optional)); */
-particlesJS.load("particles-js", "assets/particles.json", function () {
+```js
+particlesJS.load("particles-js", "assets/particles.json", () => {
console.log("callback - particles.js config loaded");
});
```
-or something like this
+After:
-```javascript
-particlesJS("particles-js", {
- /* your options here */
+```js
+tsParticles.loadJSON("tsparticles", "assets/particles.json").then(container => {
+ console.log("callback - tsParticles config loaded", container);
});
```
-All you have to do to use the new identifiers it replacing the function
-
-`particlesJS()` into `tsParticles.load()`
-
-or the function
-
-`particlesJS.load()` into `tsParticles.loadJSON()`
-
-**Warning here, the `loadJSON` doesn't have a third parameter, if you need a callback use the `then` function.**
-
-Still really simple.
-
-Let's convert the sample provided above to understand
-
-```javascript
-/* particlesJS.load(@dom-id, @path-json, @callback (optional)); */
-tsParticles.loadJSON("particles-js", "assets/particles.json").then(function (p) {
- // p is the loaded container, for using it later
- console.log("callback - particles.js config loaded");
-});
+Or with inline options:
+```js
tsParticles.load({
id: "tsparticles",
options: {
@@ -92,16 +75,26 @@ tsParticles.load({
});
```
-But probably you noticed that your warnings are still there, well the options are changed too but like the identifier this is not an issue.
+Note: `loadJSON` does not use callback as a third parameter; use `then(...)`.
+
+## 3) Update options
+
+Many legacy options still work, but updating them is recommended:
-## Transforming Options
+- `line_linked` -> `links`
+- `retina_detect` -> `detectRetina`
+- in general, `snake_case` -> `camelCase`
-Let's checkout the options warning. They suggest you to change the old property in the newer one.
+If you see console warnings, use them as a guide to update your configuration file.
-The changed properties still continues to work, but they will be dropped probably for new features.
+## Common migration pitfalls
-If you find a property with a `_` in the name, that property was renamed. We can take `line_linked` property as sample. It's renamed `lineLinked` now.
+- Updating script names but keeping old DOM ids/classes in templates
+- Migrating API calls but forgetting to convert option keys to camelCase
+- Using `loadJSON` with a callback argument instead of `then(...)`
+- Applying too many config changes at once instead of migrating incrementally
-Boom. Another warning gone!
+## 4) Next step
-Checkout warnings for finding all other properties renamed.
+- Root options and config structure: [Options](./Options.md)
+- Ready-to-use presets:
diff --git a/package.json b/package.json
index 4bdd3674c4c..99bb68f60e4 100644
--- a/package.json
+++ b/package.json
@@ -3,6 +3,7 @@
"name": "@tsparticles/workspace",
"description": "tsParticles monorepository",
"version": "0.0.0",
+ "type": "module",
"scripts": {
"slimbuild": "pnpm run prettify:readme && nx run-many -t build --parallel=50%",
"slimbuild:ci": "pnpm run prettify:ci:readme && nx run-many -t build:ci",
@@ -23,6 +24,8 @@
"publish:v3": "lerna publish from-package --dist-tag v3",
"publish:v2": "lerna publish from-package --dist-tag v2",
"publish:v1": "lerna publish from-package --dist-tag v1",
+ "release:zip-artifacts": "node scripts/package-zips.js",
+ "release:prettify-changelog": "node scripts/prettify-changelog.js",
"deploy:docs:json": "node deploy.docs-json.js",
"prepare": "husky"
},
diff --git a/paths/branches/README.md b/paths/branches/README.md
index eb97e34a75e..4c7485f4201 100644
--- a/paths/branches/README.md
+++ b/paths/branches/README.md
@@ -8,6 +8,12 @@
[tsParticles](https://github.com/tsparticles/tsparticles) path plugin for branches movement.
+## Quick checklist
+
+1. Install `@tsparticles/engine` (or use the CDN bundle below)
+2. Call the package loader function(s) before `tsParticles.load(...)`
+3. Apply the package options in your `tsParticles.load(...)` config
+
## How to use it
### CDN / Vanilla JS / jQuery
@@ -72,3 +78,34 @@ import { loadBranchesPath } from "@tsparticles/path-branches";
await loadBranchesPath(tsParticles);
})();
```
+
+## Option mapping
+
+- Primary options key: `particles.move.path`
+- Path generator name: `"branches"`
+
+```json
+{
+ "particles": {
+ "move": {
+ "enable": true,
+ "path": {
+ "enable": true,
+ "generator": "branches",
+ "options": {}
+ }
+ }
+ }
+}
+```
+
+## Common pitfalls
+
+- Calling `tsParticles.load(...)` before `loadBranchesPath(...)`
+- Verify required peer packages before enabling advanced options
+- Change one option group at a time to isolate regressions quickly
+
+## Related docs
+
+- All packages catalog:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs: /
+ if (parts.length >= 2) {
+ return `${parts[0]}/${parts[1]}`;
+ }
+
+ return null;
+}
+
+/**
+ * Extract affected packages from a PR using GitHub CLI.
+ */
+function getPackagesFromPR(prNumber) {
+ try {
+ const result = execSync(`gh pr view ${prNumber} --json files`, { encoding: "utf-8" });
+
+ const files = JSON.parse(result).files;
+ const packages = new Set();
+
+ for (const file of files) {
+ const pkg = getPackageFromPath(file.path);
+ if (pkg) {
+ packages.add(pkg);
+ }
+ }
+
+ return [...packages];
+ } catch (error) {
+ console.warn(`Failed to fetch PR #${prNumber}:`, error.message);
+ return [];
+ }
+}
+
+let output = "";
+
+// Process each line of the generated release notes
+for (const line of lines) {
+ /**
+ * Match lines like:
+ * - Add new feature (#123)
+ */
+ const match = line.match(/- (.+?) \(#(\d+)\)/);
+
+ if (!match) {
+ output += line + "\n";
+ continue;
+ }
+
+ const [, text, prNumber] = match;
+
+ const packages = getPackagesFromPR(prNumber);
+
+ if (packages.length === 0) {
+ output += `- ${text}\n`;
+ } else {
+ output += `- ${text} (${packages.join(", ")})\n`;
+ }
+}
+
+// Write final formatted changelog
+writeFileSync("RELEASE_NOTES.md", output);
+
+console.log("✅ Changelog successfully enhanced with affected packages.");
diff --git a/shapes/arrow/README.md b/shapes/arrow/README.md
index eaed77e4045..ced0a624113 100644
--- a/shapes/arrow/README.md
+++ b/shapes/arrow/README.md
@@ -8,6 +8,12 @@
[tsParticles](https://github.com/tsparticles/tsparticles) additional arrow shape.
+## Quick checklist
+
+1. Install `@tsparticles/engine` (or use the CDN bundle below)
+2. Call the package loader function(s) before `tsParticles.load(...)`
+3. Apply the package options in your `tsParticles.load(...)` config
+
## How to use it
### CDN / Vanilla JS / jQuery
@@ -73,3 +79,32 @@ import { loadArrowShape } from "@tsparticles/shape-arrow";
await loadArrowShape(tsParticles);
})();
```
+
+## Option mapping
+
+- Primary options key: `particles.shape.type: "arrow"`
+- Shape-specific options key: `particles.shape.options.arrow`
+
+```json
+{
+ "particles": {
+ "shape": {
+ "type": "arrow",
+ "options": {
+ "arrow": {}
+ }
+ }
+ }
+}
+```
+
+## Common pitfalls
+
+- Calling `tsParticles.load(...)` before `loadArrowShape(...)`
+- Verify required peer packages before enabling advanced options
+- Change one option group at a time to isolate regressions quickly
+
+## Related docs
+
+- All packages catalog:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Repository README:
diff --git a/utils/fractalNoise/README.md b/utils/fractalNoise/README.md
index 5b380f8ea77..3d6069008ca 100644
--- a/utils/fractalNoise/README.md
+++ b/utils/fractalNoise/README.md
@@ -8,6 +8,12 @@
[tsParticles](https://github.com/tsparticles/tsparticles) path plugin for fractal noise movement.
+## Quick checklist
+
+1. Install `@tsparticles/engine` (or use the CDN bundle below)
+2. Call the package loader function(s) before `tsParticles.load(...)`
+3. Apply the package options in your `tsParticles.load(...)` config
+
## How to use it
### CDN / Vanilla JS / jQuery
@@ -72,3 +78,14 @@ import { loadFractalNoisePath } from "@tsparticles/fractal-noise";
await loadFractalNoisePath(tsParticles);
})();
```
+
+## Common pitfalls
+
+- Calling `tsParticles.load(...)` before `loadFractalNoisePath(...)`
+- Verify required peer packages before enabling advanced options
+- Change one option group at a time to isolate regressions quickly
+
+## Related docs
+
+- All packages catalog:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+- Main docs:
+
`array` | `"attract"`
`"bubble"`
`"pause"`
`"push"`
`"remove"`
`"repulse"`
`"trail"`
`"emitter"`
`"absorber"` | `"emitter"` and `"absorber"` are not used by slim bundle | +Configures interactions triggered by click/tap events. + +## Properties + +| Key | Type | Example | Notes | +| -------- | ------------------ | -------------------------------------------------------------------------------- | ---------------------------------- | +| `enable` | `boolean` | `true` / `false` | Enables click interaction handling | +| `mode` | `string` / `array` | `"push"`, `"remove"`, `"repulse"`, `"bubble"`, `"attract"`, `"pause"`, `"trail"` | One or multiple click modes | + +`"emitter"` and `"absorber"` modes require their related plugin packages. + +## Quick examples + +### Add particles on click + +```json +{ + "interactivity": { + "events": { + "onClick": { + "enable": true, + "mode": "push" + } + } + } +} +``` + +### Combine push and bubble + +```json +{ + "interactivity": { + "events": { + "onClick": { + "enable": true, + "mode": ["push", "bubble"] + } + } + } +} +``` diff --git a/markdown/Options/Interactivity/Div.md b/markdown/Options/Interactivity/Div.md index d1385d74132..9e156d1ca71 100644 --- a/markdown/Options/Interactivity/Div.md +++ b/markdown/Options/Interactivity/Div.md @@ -1,8 +1,29 @@ -# On Div "Event" - -| key | option type | example | notes | -| ----------- | ----------------------- | ------------------------------------------- | ---------------------------------------------- | -| `enable` | `boolean` | `true` / `false` | | -| `mode` | `string` | `"bounce"`
`"bubble"`
`"repulse"` | | -| `selectors` | `string`
`array` | a single or an array of DOM CSS selectors | replaces the old `el` and `elementId` property | -| `type` | `string` | `"circle"`
`"rectangle"` | The div shape type | +# On Div Event + +Configures interactions bound to specific DOM elements. + +## Properties + +| Key | Type | Example | Notes | +| ----------- | ------------------ | ----------------------------------- | ---------------------------------------------------- | +| `enable` | `boolean` | `true` / `false` | Enables div-targeted interactions | +| `mode` | `string` / `array` | `"bounce"`, `"bubble"`, `"repulse"` | Interactions applied when hovering matching elements | +| `selectors` | `string` / `array` | `"#cta"` / `[".card", ".hero"]` | CSS selectors to bind | +| `type` | `string` | `"circle"` / `"rectangle"` | Interaction area shape | + +## Quick example + +```json +{ + "interactivity": { + "events": { + "onDiv": { + "enable": true, + "selectors": [".interactive-zone"], + "mode": "repulse", + "type": "circle" + } + } + } +} +``` diff --git a/markdown/Options/Interactivity/Events.md b/markdown/Options/Interactivity/Events.md index 6a4a56ce021..e5e69a4f0a0 100644 --- a/markdown/Options/Interactivity/Events.md +++ b/markdown/Options/Interactivity/Events.md @@ -1,8 +1,98 @@ # Interactivity Events -| key | option type | example | notes | -| --------------- | ----------- | ---------------- | -------------------------------------------------- | -| `onClick` | `object` | | See onClick documentation here {@link IClickEvent} | -| `onDiv` | `object` | | See onDiv documentation here {@link IDivEvent} | -| `onHover` | `object` | | See onHover documentation here {@link IHoverEvent} | -| `events.resize` | `boolean` | `true` / `false` | | +Defines which user interactions trigger particle behaviors. + +## Properties + +| Key | Type | Notes | +| --------- | --------- | --------------------------------------------------------------------------- | +| `onClick` | `object` | Triggered on mouse/touch click — see {@link IClickEvent} | +| `onDiv` | `object` | Triggered when cursor enters a specific DOM element — see {@link IDivEvent} | +| `onHover` | `object` | Triggered when cursor hovers over the canvas — see {@link IHoverEvent} | +| `resize` | `boolean` | When `true`, recalculates layout on window resize (default: `true`) | + +## Quick examples + +### Hover repulse + click push + +```json +{ + "interactivity": { + "events": { + "onHover": { + "enable": true, + "mode": "repulse" + }, + "onClick": { + "enable": true, + "mode": "push" + }, + "resize": true + } + } +} +``` + +### Hover grab (connect nearby particles to cursor) + +```json +{ + "interactivity": { + "events": { + "onHover": { + "enable": true, + "mode": "grab" + } + } + } +} +``` + +### Click remove + +```json +{ + "interactivity": { + "events": { + "onClick": { + "enable": true, + "mode": "remove" + } + } + } +} +``` + +## Available event modes + +`onHover.mode` and `onClick.mode` accept a string or array of strings from these values: + +| Mode | Description | +| ---------- | ---------------------------------------------- | +| `attract` | Pulls particles toward cursor | +| `bounce` | Bounces particles away from cursor | +| `bubble` | Enlarges / changes opacity of nearby particles | +| `connect` | Draws lines between particles near the cursor | +| `grab` | Draws a line from cursor to nearby particles | +| `light` | Simulates a light source at cursor position | +| `parallax` | Moves particles slightly in response to cursor | +| `pause` | Pauses all animation while hovering | +| `push` | Adds new particles at cursor position | +| `remove` | Removes particles near cursor | +| `repulse` | Pushes particles away from cursor | +| `slow` | Slows particles near cursor | +| `trail` | Emits particles along the cursor path | + +> Modes are configured under `interactivity.modes` — see [Modes](./Modes.md). + +## Common pitfalls + +- Enabling events without loading the required interaction plugin (e.g. `connect`, `bubble` require `@tsparticles/slim` or higher) +- Using `onDiv` without targeting a real DOM selector +- Using multiple modes in an array and not configuring each mode's options under `interactivity.modes` + +## Related docs + +- Modes configuration: [Modes](./Modes.md) +- Interactivity root: [Interactivity](../Interactivity.md) +- Options root: [Options](../../Options.md) diff --git a/markdown/Options/Interactivity/Hover.md b/markdown/Options/Interactivity/Hover.md index 58c8ae2d354..70992753f6d 100644 --- a/markdown/Options/Interactivity/Hover.md +++ b/markdown/Options/Interactivity/Hover.md @@ -1,6 +1,42 @@ # On Hover Event -| key | option type | example | notes | -| -------- | ----------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------- | -| `enable` | `boolean` | `true` / `false` | | -| `mode` | `string`
`array` | `"grab"`
`"bubble"`
`"repulse"`
`"connect"`
`["grab", "bubble"]` | the array enables all the specified modes | +Configures interactions triggered while the pointer is over the canvas. + +## Properties + +| Key | Type | Example | Notes | +| -------- | ------------------ | -------------------------------------------------------------------- | --------------------------- | +| `enable` | `boolean` | `true` / `false` | Enables hover interactions | +| `mode` | `string` / `array` | `"grab"`, `"bubble"`, `"repulse"`, `"connect"`, `["grab", "bubble"]` | One or multiple hover modes | + +## Quick examples + +### Repulse on hover + +```json +{ + "interactivity": { + "events": { + "onHover": { + "enable": true, + "mode": "repulse" + } + } + } +} +``` + +### Combined grab and bubble + +```json +{ + "interactivity": { + "events": { + "onHover": { + "enable": true, + "mode": ["grab", "bubble"] + } + } + } +} +``` diff --git a/markdown/Options/Interactivity/Modes.md b/markdown/Options/Interactivity/Modes.md index 066723ab1d2..8134958036b 100644 --- a/markdown/Options/Interactivity/Modes.md +++ b/markdown/Options/Interactivity/Modes.md @@ -1,18 +1,128 @@ # Interactivity Modes -| key | option type | example | notes | -| ----------------------- | ------------------ | ------- | ------------------------------------------------------------------------------------------------------ | -| `connect.distance` | `number` | `100` | | -| `connect.radius` | `number` | `60` | | -| `connect.links.opacity` | `number` | `0...1` | | -| `grab.distance` | `number` | `100` | | -| `grab.links.opacity` | `number` | `0...1` | | -| `bubble.distance` | `number` | `100` | | -| `bubble.size` | `number` | `40` | | -| `bubble.duration` | `number` | `0.4` | seconds | -| `repulse.distance` | `number` | `200` | | -| `repulse.duration` | `number` | `1.2` | seconds | -| `push.quantity` | `number` | `4` | | -| `remove.quantity` | `number` | `4` | | -| `emitter` | `object` / `array` | | See `Emitters` documentation
`"bounce"`
`"destroy"` | | - -## Particles Collisions Overlap - -| key | option type | example | notes | -| --------- | ----------- | ---------------- | ----- | -| `enable` | `boolean` | `true` / `false` | | -| `retries` | `number` | `1` | | +Controls how particles interact when they intersect each other. + +## Properties + +| Key | Type | Example | Notes | +| --------- | --------- | ------------------------------------- | ----------------------------------------------- | +| `enable` | `boolean` | `true` / `false` | Enables particle-to-particle collision handling | +| `mode` | `string` | `"bounce"` / `"destroy"` / `"absorb"` | Collision behavior | +| `bounce` | `object` | | Bounce tuning options, see {@link IBounce} | +| `overlap` | `object` | | Initial spawn overlap handling | + +## Collision modes + +| Mode | Behavior | +| ----------- | --------------------------------------------------------- | +| `"bounce"` | Particles bounce off each other preserving both particles | +| `"destroy"` | One particle is removed after impact | +| `"absorb"` | One particle absorbs another, increasing size/mass effect | + +## Quick examples + +### Basic bounce collisions + +```json +{ + "collisions": { + "enable": true, + "mode": "bounce" + } +} +``` + +### Arcade-style destructive collisions + +```json +{ + "collisions": { + "enable": true, + "mode": "destroy" + } +} +``` + +### Absorb collisions + +```json +{ + "collisions": { + "enable": true, + "mode": "absorb" + } +} +``` + +## Overlap options + +Controls how initial particles are placed when collisions are enabled. + +| Key | Type | Example | Notes | +| --------- | --------- | ---------------- | ----------------------------------------------------------- | +| `enable` | `boolean` | `true` / `false` | If `false`, overlapping at spawn is prevented | +| `retries` | `number` | `1` | Number of attempts to find a non-overlapping spawn position | + +### Spawn without overlaps + +```json +{ + "collisions": { + "enable": true, + "overlap": { + "enable": false, + "retries": 5 + } + } +} +``` + +## Common pitfalls + +- Enabling collisions with very high particle counts can be expensive in large canvases +- Using `mode: "destroy"` without emitters can reduce particle count quickly +- Setting `overlap.enable: false` with low `retries` can still allow occasional overlaps in crowded scenes + +## Related docs + +- Particles root: [Particles](../Particles.md) +- Move and bounce behavior: [Move](./Move.md) +- Options root: [Options](../../Options.md) diff --git a/markdown/Options/Particles/Color.md b/markdown/Options/Particles/Color.md index d47102fcf0b..fd68c307c86 100644 --- a/markdown/Options/Particles/Color.md +++ b/markdown/Options/Particles/Color.md @@ -1,18 +1,97 @@ # Particles Color -| key | option type | example | notes | -| ------------- | ----------- | ------- | --------------------------------------------------------- | ----- | -| `value` | `object` | | This `value` property is the same described {@link IColor | here} | -| `animation.h` | `object` | | See animation documentation below | -| `animation.s` | `object` | | See animation documentation below | -| `animation.l` | `object` | | See animation documentation below | - -## Particles Color Animation - -| key | option type | example | notes | -| ------------ | ----------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `enable` | `boolean` | `true` / `false` | | -| `offset.max` | `number` | `60` | | -| `offset.min` | `number` | `20` | | -| `speed` | `number` | `40` | Determines the rate (% or ° per second) at which a particle changes its
hue, saturation, or lightness. A `speed` of `0` will set the hsl of
particles to what was initially defined in `value`. | -| `sync` | `boolean` | `true` / `false` | When `sync` is toggled `true`, particles generated will change color in
time with each other for their entire duration. However, when `sync` is
toggled `false`, particles generated begin changing color at the set speed from
their time of appearance, but independently of one another. | +Controls the base color of particles and optional HSL animation over time. + +## Properties + +| Key | Type | Example | Notes | +| ------------- | ----------------------------- | -------------------------------------------------------------------------- | -------------------------------------------- | +| `value` | `string` / `array` / `object` | `"#ffffff"` / `["#ff0000", "#00ff00"]` / `{ "h": 200, "s": 100, "l": 50 }` | Same color model described in {@link IColor} | +| `animation.h` | `object` | | Hue animation options (0-360) | +| `animation.s` | `object` | | Saturation animation options (0-100) | +| `animation.l` | `object` | | Lightness animation options (0-100) | + +## Quick examples + +### Static solid color + +```json +{ + "color": { + "value": "#ffffff" + } +} +``` + +### Random color per particle from a palette + +```json +{ + "color": { + "value": ["#f43f5e", "#06b6d4", "#84cc16", "#f59e0b"] + } +} +``` + +### HSL hue animation (rainbow effect) + +```json +{ + "color": { + "value": { "h": 0, "s": 100, "l": 50 }, + "animation": { + "h": { + "enable": true, + "speed": 40, + "sync": false + } + } + } +} +``` + +### Gentle saturation/lightness breathing + +```json +{ + "color": { + "value": { "h": 200, "s": 60, "l": 50 }, + "animation": { + "s": { + "enable": true, + "speed": 5, + "offset": { "min": 10, "max": 30 }, + "sync": false + }, + "l": { + "enable": true, + "speed": 4, + "offset": { "min": 10, "max": 25 }, + "sync": false + } + } + } +} +``` + +## Color animation properties (`animation.h`, `animation.s`, `animation.l`) + +| Key | Type | Example | Notes | +| ------------ | --------- | ---------------- | ------------------------------------------------------------------------------------------ | +| `enable` | `boolean` | `true` / `false` | Enables animation for the selected channel | +| `offset.min` | `number` | `20` | Minimum random phase offset | +| `offset.max` | `number` | `60` | Maximum random phase offset | +| `speed` | `number` | `40` | Rate of change per second; `0` keeps the initial `value` | +| `sync` | `boolean` | `true` / `false` | If `true`, particles animate in lockstep; if `false`, each particle animates independently | + +## Common pitfalls + +- Using HSL animation with extremely high `speed` values can look like flicker +- Animating all three channels (`h`, `s`, `l`) at high speed can make colors unstable and hard to control +- Setting `sync: true` for all channels can produce a flat global pulse instead of natural variation + +## Related docs + +- Color formats and models: [Color](../../Color.md) +- Particles root: [Particles](../Particles.md) +- Options root: [Options](../../Options.md) diff --git a/markdown/Options/Particles/Destroy.md b/markdown/Options/Particles/Destroy.md index cbb230f8477..5a1cfa86621 100644 --- a/markdown/Options/Particles/Destroy.md +++ b/markdown/Options/Particles/Destroy.md @@ -1,15 +1,50 @@ # Particles Destroy -| key | option type | example | notes | -| ------- | ----------- | ----------------------- | ----- | -| `mode` | `string` | `"none"`
`"split"` | | -| `split` | `object` | | | - -## Particles Destroy Split - -| key | option type | example | notes | -| -------------- | ------------------ | -------------------------- | ---------------------------------------------- | ----- | -| `count` | `number` | `1` | | -| `factor.value` | `number` / `range` | `9` / `{min: 4, max: 9 }` | | -| `particles` | `object` | | See Particles options {@link IParticlesOptions | here} | -| `rate.value` | `number` / `range` | `9` / `{ min: 4, max: 9 }` | | +Controls what happens when a particle reaches its end condition. + +## Properties + +| Key | Type | Example | Notes | +| ------- | -------- | -------------------- | ------------------------------ | +| `mode` | `string` | `"none"` / `"split"` | Destroy behavior | +| `split` | `object` | | Split configuration, see below | + +## Split properties + +| Key | Type | Example | Notes | +| -------------- | ------------------ | -------------------------- | ----------------------------------------------------- | +| `count` | `number` | `1` | Number of generated particles | +| `factor.value` | `number` / `range` | `9` / `{ min: 4, max: 9 }` | Size/speed factor for spawned particles | +| `particles` | `object` | | Child particle options, see {@link IParticlesOptions} | +| `rate.value` | `number` / `range` | `9` / `{ min: 4, max: 9 }` | Spawn intensity | + +## Quick examples + +### Disable destroy behavior + +```json +{ + "destroy": { + "mode": "none" + } +} +``` + +### Split on destroy + +```json +{ + "destroy": { + "mode": "split", + "split": { + "count": 2, + "factor": { + "value": { "min": 3, "max": 6 } + }, + "rate": { + "value": 10 + } + } + } +} +``` diff --git a/markdown/Options/Particles/Group.md b/markdown/Options/Particles/Group.md index e69de29bb2d..10ffeb653e2 100644 --- a/markdown/Options/Particles/Group.md +++ b/markdown/Options/Particles/Group.md @@ -0,0 +1,50 @@ +# Particles Groups + +Defines named particle option groups that can be referenced by emitters, manual particles, or generated particles. + +## Properties + +`groups` is an object map where: + +- key: group id (`"spark"`, `"smoke"`, `"accent"`, ...) +- value: full particle options override for that group + +Each group value supports the same structure as {@link IParticlesOptions}. + +## Quick example + +```json +{ + "particles": { + "groups": { + "spark": { + "number": { + "value": 0 + }, + "color": { + "value": "#f59e0b" + }, + "size": { + "value": 2 + } + }, + "smoke": { + "number": { + "value": 0 + }, + "color": { + "value": "#94a3b8" + }, + "opacity": { + "value": 0.2 + } + } + } + } +} +``` + +## Notes + +- Group definitions do not automatically spawn particles. +- Use emitters, manual particles, or plugin features that target group ids to create grouped particles. diff --git a/markdown/Options/Particles/Life.md b/markdown/Options/Particles/Life.md index 620e8cd7572..7a16ef90b81 100644 --- a/markdown/Options/Particles/Life.md +++ b/markdown/Options/Particles/Life.md @@ -1,21 +1,43 @@ # Particles Life -| key | option type | example | notes | -| ---------- | ----------- | ------- | ----- | -| `count` | `number` | `0` | | -| `delay` | `object` | | | -| `duration` | `object` | | | +Controls particle lifespan and respawn timing. -## Particles Life Delay +## Properties -| key | option type | example | notes | -| ------- | ------------------ | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `value` | `number` / `range` | `0` / `{ min: 1, max: 5 }` | | -| `sync` | `boolean` | `true` / `false` | When `true`, all particles appear at the same time when the browser loads
the page. When `false`, particles appear with the `life.delay` value specified. | +| Key | Type | Example | Notes | +| ---------- | -------- | ------- | ------------------------------------------ | +| `count` | `number` | `0` | Number of life cycles (`0` means infinite) | +| `delay` | `object` | | Delay before each life starts | +| `duration` | `object` | | Active lifetime duration | -## Particles Life Duration +## Delay -| key | option type | example | notes | -| ------- | ------------------ | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| `value` | `number` / `range` | `0` / `{ min: 1, max: 5 }` | | -| `sync` | `boolean` | `true` / `false` | When `true`, the particle durations will be coordinated with one another.
In other words, they will all appear and disappear at the same time. | +| Key | Type | Example | Notes | +| ------- | ------------------ | -------------------------- | ----------------------------------------------------------- | +| `value` | `number` / `range` | `0` / `{ min: 1, max: 5 }` | Delay in seconds | +| `sync` | `boolean` | `true` / `false` | `true`: particles start together, `false`: staggered starts | + +## Duration + +| Key | Type | Example | Notes | +| ------- | ------------------ | -------------------------- | ----------------------------------------------------------- | +| `value` | `number` / `range` | `0` / `{ min: 1, max: 5 }` | Duration in seconds | +| `sync` | `boolean` | `true` / `false` | `true`: particles end together, `false`: independent timing | + +## Quick example + +```json +{ + "life": { + "count": 3, + "delay": { + "value": { "min": 0.5, "max": 2 }, + "sync": false + }, + "duration": { + "value": { "min": 2, "max": 4 }, + "sync": false + } + } +} +``` diff --git a/markdown/Options/Particles/Links.md b/markdown/Options/Particles/Links.md index 42afccbd9ca..8163e5dd832 100644 --- a/markdown/Options/Particles/Links.md +++ b/markdown/Options/Particles/Links.md @@ -1,31 +1,131 @@ # Particles Links -| key | option type | example | notes | -| ----------- | -------------- | ---------------- | --------------------------------------------------------------------------------------------------------------- | -| `blink` | `boolean` | `true` / `false` | This option works with `color` with "random" value, if set to `true` the links will blink with random colors | -| `color` | `color object` | | This `color` object is the same described here {@links IColor} | -| `consent` | `boolean` | `true` / `false` | This option works with `color` with "random" value, if set to `true` the links will have a random common color | -| `distance` | `number` | `150` | | -| `enable` | `boolean` | `true` / `false` | | -| `id` | `string` | `"link1"` | This `id` is optional, when specified the particles with the same link `id` will be linked together, if enabled | -| `opacity` | `number` | `0...1` | | -| `shadow` | `object` | | See shadow documentation below | -| `triangles` | `object` | | See triangles documentation below | -| `warp` | `boolean` | `true` / `false` | | -| `width` | `number` | `1.5` | | +Draws lines between nearby particles, creating a web-like effect. + +> Requires `@tsparticles/slim` or higher (not available in `@tsparticles/basic`). + +## Properties + +| Key | Type | Example | Notes | +| ----------- | --------------------- | ---------------- | -------------------------------------------------------------------------- | +| `enable` | `boolean` | `true` / `false` | Activates link drawing | +| `distance` | `number` | `150` | Max px distance between particles for a link to appear | +| `color` | color object / string | `"#ffffff"` | See {@link IColor} | +| `opacity` | `number` | `0.4` | Link line opacity (0–1) | +| `width` | `number` | `1.5` | Link line width in pixels | +| `blink` | `boolean` | `true` / `false` | When `color` is `"random"`, makes links blink with different random colors | +| `consent` | `boolean` | `true` / `false` | When `color` is `"random"`, all links share one common random color | +| `id` | `string` | `"group1"` | Only particles with the same `id` are linked | +| `warp` | `boolean` | `true` / `false` | Links wrap around canvas edges | +| `shadow` | `object` | | See [Links Shadow](#links-shadow) | +| `triangles` | `object` | | See [Links Triangles](#links-triangles) | + +## Quick examples + +### Basic links web + +```json +{ + "links": { + "enable": true, + "distance": 150, + "color": "#ffffff", + "opacity": 0.4, + "width": 1 + } +} +``` + +### Colored random-blink links + +```json +{ + "links": { + "enable": true, + "distance": 120, + "color": "random", + "blink": true, + "opacity": 0.6 + } +} +``` + +### Links with triangles fill + +```json +{ + "links": { + "enable": true, + "distance": 150, + "color": "#4f46e5", + "triangles": { + "enable": true, + "color": "#4f46e5", + "opacity": 0.1 + } + } +} +``` + +### Grouped links (only within same id) + +```json +{ + "particles": { + "groups": { + "teamA": { + "links": { "enable": true, "id": "teamA", "color": "#ff0000" } + }, + "teamB": { + "links": { "enable": true, "id": "teamB", "color": "#0000ff" } + } + } + } +} +``` ## Links Shadow -| key | option type | example | notes | -| -------- | ----------------------------- | ---------------- | -------------------------------------------------------------- | -| `blur` | `number` | `4` | | -| `color` | `string`
`color object` | | This `color` object is the same described here {@links IColor} | -| `enable` | `boolean` | `true` / `false` | | +Adds a blur glow effect to link lines. + +| Key | Type | Example | Notes | +| -------- | --------------------- | ---------------- | --------------------- | +| `enable` | `boolean` | `true` / `false` | Activates shadow | +| `blur` | `number` | `4` | Blur radius in pixels | +| `color` | string / color object | `"#ffffff"` | Shadow color | + +```json +{ + "links": { + "enable": true, + "shadow": { + "enable": true, + "blur": 5, + "color": "#00ffff" + } + } +} +``` ## Links Triangles -| key | option type | example | notes | -| --------- | ----------------------------- | ---------------- | -------------------------------------------------------------- | -| `color` | `string`
`color object` | | This `color` object is the same described here {@links IColor} | -| `enable` | `boolean` | `true` / `false` | | -| `opacity` | `number` | `0...1` | | +Fills triangles formed by three nearby linked particles. + +| Key | Type | Example | Notes | +| --------- | --------------------- | ---------------- | ----------------------- | +| `enable` | `boolean` | `true` / `false` | Activates triangle fill | +| `color` | string / color object | `"#ffffff"` | Triangle fill color | +| `opacity` | `number` | `0.1` | Fill opacity (0–1) | + +## Common pitfalls + +- Using `links` without loading a bundle that includes it (`@tsparticles/slim` or higher) +- Setting `distance` too low — with few particles spread across a large canvas, no links will appear +- Using `blink: true` and `consent: true` at the same time — `consent` takes precedence +- Setting `id` without configuring groups — standalone particles won't link at all + +## Related docs + +- Particles root: [Particles](../Particles.md) +- Color formats: [Color](../../Color.md) +- Options root: [Options](../../Options.md) diff --git a/markdown/Options/Particles/Move.md b/markdown/Options/Particles/Move.md index 88f1f64d8ba..3aee07b11b5 100644 --- a/markdown/Options/Particles/Move.md +++ b/markdown/Options/Particles/Move.md @@ -1,84 +1,210 @@ # Particles Move -| key | option type | example | notes | -| ----------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | -| `angle` | `object` | | See angle documentation below | -| `attract` | `object` | | See attract documentation below | -| `direction` | `string` | `"none"`
`"top"`
`"top-right"`
`"right"`
`"bottom-right"`
`"bottom"`
`"bottom-left"`
`"left"`
`"top-left"` | | -| `distance` | `object` | | See distance documentation below | -| `enable` | `boolean` | `true` / `false` | | -| `gravity` | `object` | | See gravity documentation below | -| `noise` | `object` | | See noise documentation below | -| `outModes` | `object` | | See out modes documentation below | -| `random` | `boolean` | `true` / `false` | | -| `size` | `boolean` | `true` / `false` | | -| `speed` | `number` | `4` | assuming a predefined distance for the particle to travel, `speed` is the amount of time takes to travel the predefined distance for any particle | -| `straight` | `boolean` | `true` / `false` | | -| `trail` | `object` | | See trail documentation below | -| `vibrate` | `boolean` | `true` / `false` | | -| `warp` | `boolean` | `true` / `false` | | +Controls how particles move across the canvas — direction, speed, gravity, noise, and boundary behavior. + +## Core properties + +| Key | Type | Example | Notes | +| ----------- | ------------------ | ----------------------------------- | ------------------------------------------------------------------------------------------ | +| `enable` | `boolean` | `true` / `false` | Activates movement | +| `speed` | `number` / `range` | `4` / `{ min: 1, max: 6 }` | Movement speed (relative units) | +| `direction` | `string` | `"none"` / `"top"` / `"bottom"` / … | Initial direction; full list below | +| `random` | `boolean` | `true` / `false` | Randomizes initial speed per particle | +| `straight` | `boolean` | `true` / `false` | When `true`, particles move in a fixed straight line | +| `vibrate` | `boolean` | `true` / `false` | Adds a vibration tremor effect | +| `warp` | `boolean` | `true` / `false` | Particles reappear on the opposite edge | +| `size` | `boolean` | `true` / `false` | Speed scales with particle size | +| `outModes` | `object` | | Behavior when particles reach canvas boundary — see [Out Modes](#particles-move-out-modes) | +| `angle` | `object` | | Spread angle offset — see [Angle](#particles-move-angle) | +| `attract` | `object` | | Attract toward a center point — see [Attract](#particles-move-attract) | +| `gravity` | `object` | | Gravity acceleration — see [Gravity](#particles-move-gravity) | +| `noise` | `object` | | Perlin/Simplex noise path — see [Noise](#particles-move-noise) | +| `trail` | `object` | | Trailing ghost effect — see [Trail](#particles-move-trail) | +| `spin` | `object` | | Spin around a center point — see [Spin](#particles-move-spin) | + +## Direction values + +`"none"` · `"top"` · `"top-right"` · `"right"` · `"bottom-right"` · `"bottom"` · `"bottom-left"` · `"left"` · `"top-left"` + +## Quick examples + +### Basic random movement + +```json +{ + "move": { + "enable": true, + "speed": 2 + } +} +``` + +### Falling particles (snow-like) + +```json +{ + "move": { + "enable": true, + "direction": "bottom", + "speed": 1.5, + "straight": false + } +} +``` + +### Rising particles (fire-like) with gravity off-screen destroy + +```json +{ + "move": { + "enable": true, + "direction": "top", + "speed": 3, + "outModes": { + "default": "destroy", + "bottom": "none" + } + } +} +``` + +### Gravity + bounce + +```json +{ + "move": { + "enable": true, + "gravity": { + "enable": true, + "acceleration": 9.81, + "maxSpeed": 50 + }, + "outModes": { + "default": "bounce", + "top": "none" + } + } +} +``` + +### Noise path (organic wandering) + +```json +{ + "move": { + "enable": true, + "noise": { + "enable": true, + "delay": { "value": 0 } + } + } +} +``` + +## Particles Move Out Modes + +Controls what happens when a particle exits the canvas boundary. + +| Value | Behavior | +| --------------------- | -------------------------------- | +| `"out"` | Wraps to the opposite side | +| `"destroy"` | Removes the particle | +| `"bounce"` | Bounces off the boundary | +| `"bounce-horizontal"` | Bounces only on horizontal edges | +| `"bounce-vertical"` | Bounces only on vertical edges | +| `"none"` | No special behavior | +| `"split"` | Splits the particle on exit | + +```json +{ + "outModes": { + "default": "out", + "top": "destroy", + "bottom": "bounce" + } +} +``` + +`default` applies to all sides not explicitly overridden. You can set `top`, `bottom`, `left`, `right` independently. ## Particles Move Angle -| key | option type | example | notes | -| -------- | ----------- | ---------------- | ----- | -| `offset` | `boolean` | `true` / `false` | | -| `value` | `number` | `3000` | | +Applies a spread offset angle to particle direction. -## Particles Move Attract +| Key | Type | Example | Notes | +| -------- | -------- | ------- | --------------------------------- | +| `value` | `number` | `90` | Spread angle in degrees | +| `offset` | `number` | `45` | Angular offset added to direction | -| key | option type | example | notes | -| ---------- | ----------- | ---------------- | ----- | -| `enable` | `boolean` | `true` / `false` | | -| `rotate.x` | `number` | `3000` | | -| `rotate.y` | `number` | `1500` | | +## Particles Move Attract -## Particles Move Distance +Pulls particles toward a virtual center defined by rotation axes. -| key | option type | example | notes | -| ------------ | ----------- | ------- | ----- | -| `horizontal` | `number` | `50` | | -| `vertical` | `number` | `50` | | +| Key | Type | Example | Notes | +| ---------- | --------- | ---------------- | ---------------------- | +| `enable` | `boolean` | `true` / `false` | Activates attract | +| `rotate.x` | `number` | `3000` | X-axis rotation factor | +| `rotate.y` | `number` | `1500` | Y-axis rotation factor | ## Particles Move Gravity -| key | option type | example | notes | -| -------------- | ----------- | ---------------- | ----- | -| `acceleration` | `number` | `9.81` | | -| `enable` | `boolean` | `true` / `false` | | -| `maxSpeed` | `number` | `50` | | +Simulates gravitational acceleration pulling particles downward. + +| Key | Type | Example | Notes | +| -------------- | --------- | ---------------- | -------------------------- | +| `enable` | `boolean` | `true` / `false` | Activates gravity | +| `acceleration` | `number` | `9.81` | Gravity acceleration value | +| `maxSpeed` | `number` | `50` | Caps falling speed | ## Particles Move Noise -| key | option type | example | notes | -| ------------- | ------------------- | ------------------------------ | ----- | -| `clamp` | `boolean` | `true` / `false` | | -| `delay.value` | `number` / `object` | `1` / `{ min: 0.5, max: 1.5 }` | | -| `enable` | `boolean` | `true` / `false` | | -| `generator` | `string` | `"generator name"` | | +Applies Perlin/Simplex noise for organic non-linear paths. -## Particles Move Out Modes - -| key | option type | example | notes | -| --------- | ----------- | ---------------------------------------------------------------------------- | ----- | -| `default` | `string` | `"out"`
`"destroy"`
`"bounce"`
`"none"`
`"split"` | | -| `bottom` | `string` | `"out"`
`"destroy"`
`"bounce"`
`"none"`
`"split"` | | -| `left` | `string` | `"out"`
`"destroy"`
`"bounce"`
`"none"`
`"split"` | | -| `right` | `string` | `"out"`
`"destroy"`
`"bounce"`
`"none"`
`"split"` | | -| `top` | `string` | `"out"`
`"destroy"`
`"bounce"`
`"none"`
`"split"` | | +| Key | Type | Example | Notes | +| ------------- | ------------------ | ------------------------------ | ---------------------------------- | +| `enable` | `boolean` | `true` / `false` | Activates noise movement | +| `delay.value` | `number` / `range` | `1` / `{ min: 0.5, max: 1.5 }` | Delay before noise kicks in | +| `clamp` | `boolean` | `true` / `false` | Clamps noise to canvas bounds | +| `generator` | `string` | `"simplexNoise"` | Name of the noise generator plugin | ## Particles Move Spin -| key | option type | example | notes | -| -------------- | ----------- | ------------------ | ----- | -| `acceleration` | `number` | `2` | | -| `enable` | `boolean` | `true` / `false` | | -| `position` | `object` | `{ x: 50, y: 50 }` | | +Rotates particles around a center point. + +| Key | Type | Example | Notes | +| -------------- | --------- | ---------------------- | --------------------------- | +| `enable` | `boolean` | `true` / `false` | Activates spin | +| `acceleration` | `number` | `2` | Angular acceleration | +| `position` | `object` | `{ "x": 50, "y": 50 }` | Center point as % of canvas | ## Particles Move Trail -| key | option type | example | notes | -| ----------- | -------------- | ---------------- | -------------------------------------------------------------- | -| `enable` | `boolean` | `true` / `false` | | -| `length` | `number` | `10` | | -| `fillColor` | `color object` | | This `color` object is the same described here {@links IColor} | +Renders a fading trail behind each particle. + +| Key | Type | Example | Notes | +| ----------- | --------------------- | ---------------- | ---------------------------- | +| `enable` | `boolean` | `true` / `false` | Activates trail | +| `length` | `number` | `10` | Number of trail frames | +| `fillColor` | color object / string | `"#000000"` | Color used to fade the trail | + +## Particles Move Distance + +Limits how far a particle can travel from its origin. + +| Key | Type | Example | Notes | +| ------------ | -------- | ------- | ------------------------------- | +| `horizontal` | `number` | `50` | Max horizontal travel in pixels | +| `vertical` | `number` | `50` | Max vertical travel in pixels | + +## Common pitfalls + +- Setting `enable: false` and expecting particles to animate — all movement is disabled +- Using `gravity` with `outModes: "out"` — particles will fall off the bottom and wrap to the top, which looks wrong; use `"destroy"` or `"bounce"` for gravity scenarios +- Enabling `noise` without loading the noise plugin +- Combining `straight: true` with a non-`"none"` noise generator — `straight` overrides noise + +## Related docs + +- Particles root: [Particles](../Particles.md) +- Out Modes: covered above +- Options root: [Options](../../Options.md) diff --git a/markdown/Options/Particles/Number.md b/markdown/Options/Particles/Number.md index 5c45b7201bd..3a8ab567d7c 100644 --- a/markdown/Options/Particles/Number.md +++ b/markdown/Options/Particles/Number.md @@ -1,8 +1,73 @@ # Particles Number -| key | option type | example | notes | -| ----------------------- | ----------- | ---------------- | ------------------------------ | -| `number.value` | `number` | `40` | | -| `number.limit` | `number` | `200` | `0` or less disables the limit | -| `number.density.enable` | `boolean` | `true` / `false` | | -| `number.density.area` | `number` | `800` | | +Controls how many particles exist and how their count is distributed across the canvas. + +## Properties + +| Key | Type | Example | Notes | +| ---------------- | --------- | ---------------- | --------------------------------------------------------- | +| `value` | `number` | `40` | Total particle count | +| `limit` | `number` | `200` | Maximum allowed particles; `0` or less disables the limit | +| `density.enable` | `boolean` | `true` / `false` | Scales particle count based on canvas area | +| `density.area` | `number` | `800` | Reference area (px²) used for density calculation | + +## Quick examples + +### Fixed count + +```json +{ + "number": { + "value": 60 + } +} +``` + +### Density-based count (adapts to screen size) + +```json +{ + "number": { + "value": 80, + "density": { + "enable": true, + "area": 800 + } + } +} +``` + +With `density.enable: true`, the actual particle count is calculated as: + +``` +count = value × (canvas area / area) +``` + +A `800×600` canvas with `value: 80` and `area: 800` will render approximately 60 particles. +A `1920×1080` canvas with the same config will render approximately 259 particles. + +### With a cap + +```json +{ + "number": { + "value": 80, + "limit": 150, + "density": { + "enable": true, + "area": 800 + } + } +} +``` + +## Common pitfalls + +- Setting a very high `value` without density enabled causes performance issues on small screens +- Setting `density.enable: true` but not adjusting `value` and `area` together leads to unexpected counts +- `limit` is a hard cap and applies after density calculation; if density produces a higher count, the excess is silently dropped + +## Related docs + +- Particles root: [Particles](../Particles.md) +- Options root: [Options](../../Options.md) diff --git a/markdown/Options/Particles/Opacity.md b/markdown/Options/Particles/Opacity.md index 4205193874c..a8f4222cb3b 100644 --- a/markdown/Options/Particles/Opacity.md +++ b/markdown/Options/Particles/Opacity.md @@ -1,10 +1,79 @@ # Particles Opacity -| key | option type | example | notes | -| ---------------------- | ------------------ | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `value` | `number` / `range` | `0...1` / `{ min: 0.1, max: 0.8 }` | | -| `animation.destroy` | `string` | `min`
`max`
`none` | Destroys the particles if not `none` when it reaches the `min` or `max`
value of the animation | -| `animation.enable` | `boolean` | `true` / `false` | | -| `animation.speed` | `number` | `3` | Rate expressed as % per second for particle opacity values to reach min and max
specified opacity values | -| `animation.startValue` | `string` | `min`
`max`
`random` | Defines where is the starting value of the animation, if `random` property
is set this will be ignored | -| `animation.sync` | `boolean` | `true` / `false` | Unless `animation.startValue` is set to `random`, when `sync` is toggled
`true`, particles will change opacity simultaneously for their entire
duration; when `false`, particles begin changing opacity from their
time of appearance, but independently of one another. | +Controls the transparency of particles, including animated fading effects. + +## Properties + +| Key | Type | Example | Notes | +| ---------------------- | ------------------ | -------------------------------- | ----------------------------------------------------------- | +| `value` | `number` / `range` | `0.5` / `{ min: 0.1, max: 0.8 }` | Base opacity (0–1) | +| `animation.enable` | `boolean` | `true` / `false` | Animates opacity over time | +| `animation.speed` | `number` | `3` | Rate of change (% per second toward min/max) | +| `animation.startValue` | `string` | `min` / `max` / `random` | Starting point of the animation | +| `animation.sync` | `boolean` | `true` / `false` | When `true`, all particles fade in sync | +| `animation.destroy` | `string` | `min` / `max` / `none` | Destroys the particle when opacity reaches the chosen bound | + +## Quick examples + +### Static opacity + +```json +{ + "opacity": { + "value": 0.5 + } +} +``` + +### Random opacity per particle + +```json +{ + "opacity": { + "value": { "min": 0.2, "max": 0.8 } + } +} +``` + +### Animated fade-in/out (twinkle-like effect) + +```json +{ + "opacity": { + "value": { "min": 0.1, "max": 1 }, + "animation": { + "enable": true, + "speed": 1, + "startValue": "random", + "sync": false + } + } +} +``` + +### Fade out and destroy + +```json +{ + "opacity": { + "value": 1, + "animation": { + "enable": true, + "speed": 0.5, + "startValue": "max", + "destroy": "min" + } + } +} +``` + +## Common pitfalls + +- Setting `animation.sync: true` with `startValue: random` — `sync` is ignored when `startValue` is `random` +- Using `destroy: "min"` without an emitter refilling particles leads to an empty canvas over time + +## Related docs + +- Particles root: [Particles](../Particles.md) +- Size (same animation shape): [Size](./Size.md) +- Options root: [Options](../../Options.md) diff --git a/markdown/Options/Particles/Orbit.md b/markdown/Options/Particles/Orbit.md index 7744ba23cea..fa9438fec52 100644 --- a/markdown/Options/Particles/Orbit.md +++ b/markdown/Options/Particles/Orbit.md @@ -1,12 +1,36 @@ # Particles Orbit -| key | option type | example | notes | -| ------------------ | ------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------- | -| `animation.enable` | `boolean` | `true` / `false` | | -| `animation.speed` | `number` | `0` | describes the rate of travel of a particle progressing along the
curve defined by other values in this property | -| `color` | `color object` | | This `color` object is the same described here {@links IColor} | -| `enable` | `object` | `true` / `false` | | -| `radius` | `number` | `0` | | -| `rotation.value` | `number` / `object` | `50` / `{ min: 10, max: 50 }` | | -| `opacity` | `number` | | | -| `width` | `number` | | | +Adds orbital movement around a center, optionally drawing visible orbit trails. + +## Properties + +| Key | Type | Example | Notes | +| ------------------ | ------------------ | ----------------------------- | ------------------------------------ | +| `enable` | `boolean` | `true` / `false` | Enables orbit behavior | +| `radius` | `number` | `0` | Orbit radius | +| `rotation.value` | `number` / `range` | `50` / `{ min: 10, max: 50 }` | Rotation amount | +| `animation.enable` | `boolean` | `true` / `false` | Enables orbit animation | +| `animation.speed` | `number` | `0` | Orbit animation speed | +| `color` | `color object` | | Orbit path color, see {@link IColor} | +| `opacity` | `number` | `0.5` | Orbit line opacity | +| `width` | `number` | `1` | Orbit line width | + +## Quick example + +```json +{ + "orbit": { + "enable": true, + "radius": 20, + "rotation": { + "value": { "min": 10, "max": 40 } + }, + "animation": { + "enable": true, + "speed": 2 + }, + "opacity": 0.3, + "width": 1 + } +} +``` diff --git a/markdown/Options/Particles/Repulse.md b/markdown/Options/Particles/Repulse.md index 4cfb302b2bb..bcfe8f52938 100644 --- a/markdown/Options/Particles/Repulse.md +++ b/markdown/Options/Particles/Repulse.md @@ -1,10 +1,29 @@ # Particles Repulse -| key | option type | example | notes | -| ---------- | ------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `enable` | `boolean` | `true` / `false` | | -| `distance` | `number` | `100` | | -| `duration` | `number` | `2` | | -| `factor` | `number` | `1` | | -| `speed` | `number` | `100` | The rate in seconds at which a particle will disperse
from around the cursor at any given time. A
`repulse` speed of `0` will result in no effect
on the particles. | -| `value` | `number` / `object` | `50` / `{ min: 10, max: 50 }` | | +Configures particle-to-particle repulsion behavior. + +## Properties + +| Key | Type | Example | Notes | +| ---------- | ------------------ | ----------------------------- | -------------------------- | +| `enable` | `boolean` | `true` / `false` | Enables repulse behavior | +| `distance` | `number` | `100` | Repulse distance | +| `duration` | `number` | `2` | Effect duration in seconds | +| `factor` | `number` | `1` | Repulse force multiplier | +| `speed` | `number` | `100` | Displacement speed | +| `value` | `number` / `range` | `50` / `{ min: 10, max: 50 }` | Base repulse intensity | + +## Quick example + +```json +{ + "repulse": { + "enable": true, + "distance": 120, + "duration": 1.5, + "factor": 1, + "speed": 80, + "value": { "min": 20, "max": 60 } + } +} +``` diff --git a/markdown/Options/Particles/Roll.md b/markdown/Options/Particles/Roll.md index 4eb10b6a53c..68c39345132 100644 --- a/markdown/Options/Particles/Roll.md +++ b/markdown/Options/Particles/Roll.md @@ -1,11 +1,34 @@ -# Particles Rotate - -| key | option type | example | notes | -| ------------------ | ------------------ | -------------------------- | --------------------------------------------------------------------------------------------------------------------- | -| `backColor` | `color object` | | This `color` object is the same described here {@links IColor} | -| `darken.enable` | `boolean` | `true` / `false` | | -| `darken.value` | `number` | `5` | The percent value subtracted to the particle fill color luminosity | -| `enable` | `boolean` | `true` / `false` | | -| `enlighten.enable` | `boolean` | `true` / `false` | | -| `enlighten.value` | `number` | `5` | The percent value added to the particle fill color luminosity | -| `speed` | `number` / `range` | `0` / `{ min: 1, max: 5 }` | Describes the rate of travel of a particle progressing along the
curve defined by other values in this property. | +# Particles Roll + +Adds a rolling effect that changes perceived front/back shading while particles move. + +## Properties + +| Key | Type | Example | Notes | +| ------------------ | ------------------ | -------------------------- | ----------------------------------- | +| `enable` | `boolean` | `true` / `false` | Enables roll effect | +| `speed` | `number` / `range` | `0` / `{ min: 1, max: 5 }` | Roll speed | +| `backColor` | `color object` | | Back-face color, see {@link IColor} | +| `darken.enable` | `boolean` | `true` / `false` | Enables darkening on rotation | +| `darken.value` | `number` | `5` | Percent of darkness | +| `enlighten.enable` | `boolean` | `true` / `false` | Enables lightening on rotation | +| `enlighten.value` | `number` | `5` | Percent of lightness | + +## Quick example + +```json +{ + "roll": { + "enable": true, + "speed": { "min": 2, "max": 6 }, + "darken": { + "enable": true, + "value": 15 + }, + "enlighten": { + "enable": false, + "value": 0 + } + } +} +``` diff --git a/markdown/Options/Particles/Rotate.md b/markdown/Options/Particles/Rotate.md index 728662b41f2..aa4931272b7 100644 --- a/markdown/Options/Particles/Rotate.md +++ b/markdown/Options/Particles/Rotate.md @@ -1,10 +1,31 @@ # Particles Rotate -| key | option type | example | notes | -| ------------------ | ------------------ | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `direction` | `string` | `"clockwise` / `counter-clockwise"` / `"random"` | | -| `path` | `boolean` | `true` / `false` | | -| `value` | `number` / `range` | `0` / `{ min: 90, max: 270 }` | angle in degrees | -| `animation.enable` | `boolean` | `true` / `false` | | -| `animation.speed` | `number` | `5` | Rate at which a particle turns expressed in degrees per second | -| `animation.sync` | `boolean` | `true` / `false` | When `sync` is toggled `true`, particles generated will rotate in
time with each other for their entire duration. However, when `sync` is
toggled `false`, particles generated begin turning at the set speed from
their time of appearance, but independently of one another. | +Controls particle rotation angle and rotation animation. + +## Properties + +| Key | Type | Example | Notes | +| ------------------ | ------------------ | -------------------------------------------------- | ------------------------------------ | +| `direction` | `string` | `"clockwise"` / `"counter-clockwise"` / `"random"` | Rotation direction | +| `path` | `boolean` | `true` / `false` | Rotates according to movement path | +| `value` | `number` / `range` | `0` / `{ min: 90, max: 270 }` | Base angle in degrees | +| `animation.enable` | `boolean` | `true` / `false` | Enables continuous rotation | +| `animation.speed` | `number` | `5` | Degrees per second | +| `animation.sync` | `boolean` | `true` / `false` | `true`: all particles rotate in sync | + +## Quick example + +```json +{ + "rotate": { + "value": { "min": 0, "max": 360 }, + "direction": "random", + "path": false, + "animation": { + "enable": true, + "speed": 25, + "sync": false + } + } +} +``` diff --git a/markdown/Options/Particles/Shadow.md b/markdown/Options/Particles/Shadow.md index c07fa943706..ec469c28dee 100644 --- a/markdown/Options/Particles/Shadow.md +++ b/markdown/Options/Particles/Shadow.md @@ -1,9 +1,31 @@ # Particles Shadow -| key | option type | example | notes | -| ---------- | -------------- | ---------------- | -------------------------------------------------------------- | -| `blur` | `number` | `4` | | -| `color` | `color object` | | This `color` object is the same described here {@links IColor} | -| `enable` | `boolean` | `true` / `false` | | -| `offset.x` | `number` | `10` | | -| `offset.y` | `number` | `10` | | +Adds a canvas shadow behind each particle. + +## Properties + +| Key | Type | Example | Notes | +| ---------- | -------------- | ---------------- | -------------------------------- | +| `enable` | `boolean` | `true` / `false` | Enables particle shadow | +| `blur` | `number` | `4` | Blur radius | +| `color` | `color object` | | Shadow color, see {@link IColor} | +| `offset.x` | `number` | `10` | Horizontal offset | +| `offset.y` | `number` | `10` | Vertical offset | + +## Quick example + +```json +{ + "shadow": { + "enable": true, + "blur": 8, + "color": { + "value": "#60a5fa" + }, + "offset": { + "x": 2, + "y": 2 + } + } +} +``` diff --git a/markdown/Options/Particles/Shape.md b/markdown/Options/Particles/Shape.md index 5eaad516ea6..a36bb7cb67f 100644 --- a/markdown/Options/Particles/Shape.md +++ b/markdown/Options/Particles/Shape.md @@ -1,44 +1,61 @@ # Shape -The Shape section of Particles options has been reworked a lot but for now it's still compatible with all your old -configurations. +Controls the visual shape of particles. Supports built-in shapes, images, emoji, and custom registered shapes. -If you want to customize more you particles you should use the new syntax +## Core properties -| key | option type | example | notes | -| --------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | -| `type` | `string`
`array` | `"circle"`
`"line"`
`"edge"`
`"triangle"`
`"polygon"`
`"star"`
`"image"`
`["circle", "triangle", "image"]` | | -| `options` | `object` | | This object is where new implementations are placed | +| Key | Type | Example | Notes | +| --------- | ------------------ | --------------------------------- | ------------------------------------------------------------------- | +| `type` | `string` / `array` | `"circle"` / `["circle", "star"]` | Shape type(s) to use; if array, one is picked randomly per particle | +| `options` | `object` | | Per-shape configuration — keys match shape type names | -## Shape Options +## Built-in shape types -Shape `options` is a dynamic object, is properties are the shape types, even the custom one you created (as you can read -above) and the values are objects or arrays that will be used to draw the particles. +| Value | Description | Bundle required | +| ------------------------ | ---------------------------- | -------------------- | +| `"circle"` | Filled circle | `@tsparticles/basic` | +| `"edge"` / `"square"` | Square | `@tsparticles/slim` | +| `"triangle"` | Triangle | `@tsparticles/slim` | +| `"polygon"` | Regular polygon with N sides | `@tsparticles/slim` | +| `"star"` | Star with N points | `@tsparticles/slim` | +| `"line"` | Straight line | `@tsparticles/slim` | +| `"image"` / `"images"` | External image or SVG | `@tsparticles/slim` | +| `"character"` / `"char"` | Text / emoji character | `@tsparticles/slim` | -This will give us more customization, you can now specify a shape type with a `particles` property that lets you -customize almost all the properties of the original object. +## Quick examples -`shape` and `number` will be ignored for obvious reasons. +### Circle (default) -The shape types you find described above are the only implemented here, if you use an external custom shape ask the -creator. - -All the shapes have in common these properties +```json +{ + "shape": { + "type": "circle" + } +} +``` -| key | option type | example | notes | -| ----------- | ----------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------- | -| `particles` | `object` | | See Particles options [here](https://particles.js.org/docs/interfaces/_options_interfaces_ioptions_.ioptions.html-Particles) | -| `fill` | `boolean` | `true` / `false` | Used to specify if its shape particles should be filled with color or not | -| `close` | `boolean` | `true` / `false` | Used to specify if its shape particles should have a closed shape | +### Random mix of shapes -Below you'll find the options of some shape types that need additional properties, you can add to the object below the 3 -properties above. +```json +{ + "shape": { + "type": ["circle", "triangle", "star"] + } +} +``` -### Polygon +### Polygon (hexagon) -```javascript -polygon: { - sides: 5; // the number of sides of the polygon +```json +{ + "shape": { + "type": "polygon", + "options": { + "polygon": { + "sides": 6 + } + } + } } ``` @@ -46,22 +63,32 @@ polygon: { ```json { - "star": { - "sides": 5, // the number of sides of the star - "inset": 2 // the inset length, 2 is the default and an acceptable value + "shape": { + "type": "star", + "options": { + "star": { + "sides": 5, + "inset": 2 + } + } } } ``` -### Character / Char +### Emoji particles ```json { - "character": { - "value": "*", // the text to use as particles, any string is valid, for escaping unicode char use the `\uXXXX` syntax - "font": "Verdana", // the font to use to draw the text. If the font needs an external css or javascript like FontAwesome you should include all the necessary files on your own - "style": "", // any additional css style to add to the text - "weight": "" // the css weight property, some fonts like font awesome have a specified weight, check the documentation if needed + "shape": { + "type": "character", + "options": { + "character": { + "value": ["❄️", "⛄", "🌨️"], + "font": "Segoe UI Emoji", + "style": "", + "weight": "400" + } + } } } ``` @@ -70,15 +97,61 @@ polygon: { ```json { - "image": { - // any path or url to your image that will be used as a particle - "src": "http://mywebsite.com/assets/img/image.png", - // the pixel width of the image, you can use any value, the image will be scaled - "width": 100, - // the pixel height of the image, you can use any value, the image will be scaled - "height": 100, - // if true and the image type is SVG, it will replace all the colors with the particle color - "replaceColor": false + "shape": { + "type": "image", + "options": { + "image": { + "src": "https://example.com/logo.png", + "width": 32, + "height": 32, + "replaceColor": false + } + } } } ``` + +Set `replaceColor: true` for SVG images to tint them with the particle `color`. + +### Custom registered shape + +```javascript +tsParticles.addShape("myShape", drawer); +``` + +```json +{ + "shape": { + "type": "myShape", + "options": { + "myShape": { + "close": true, + "fill": true + } + } + } +} +``` + +## Shape options common properties + +All shape types accept these properties inside their `options` object: + +| Key | Type | Notes | +| ----------- | --------- | ------------------------------------------------------------ | +| `fill` | `boolean` | Fill the shape with color | +| `close` | `boolean` | Close the shape path | +| `particles` | `object` | Per-shape particle overrides (see {@link IParticlesOptions}) | + +## Common pitfalls + +- Using `"square"` or `"triangle"` with `@tsparticles/basic` — these shapes require `@tsparticles/slim` or the dedicated shape package +- Using `"image"` without providing `width` and `height` — the image may render at unexpected sizes +- Using `"character"` with an emoji that relies on an external font without including that font in the page +- Using `replaceColor: true` on raster images (PNG/JPG) — only works with SVG + +## Related docs + +- Particles root: [Particles](../Particles.md) +- Custom shapes (plugins): [Plugins](../../Plugins.md) +- Options root: [Options](../../Options.md) diff --git a/markdown/Options/Particles/Size.md b/markdown/Options/Particles/Size.md index eed62033adb..525d032c094 100644 --- a/markdown/Options/Particles/Size.md +++ b/markdown/Options/Particles/Size.md @@ -1,10 +1,80 @@ # Particles Size -| key | option type | example | notes | -| ---------------------- | ------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `value` | `number` / `object` | `50` / `{ min: 10, max: 50 }` | | -| `animation.destroy` | `string` | `min`
`max`
`none` | Destroys the particles if not `none` when it reaches the `min` or
`max` value of the animation | -| `animation.enable` | `boolean` | `true` / `false` | | -| `animation.speed` | `number` | `3` | Describes the rate at which particles will shrink or grow as a
function of other `size` values | -| `animation.startValue` | `string` | `min`
`max`
`random` | Defines where is the starting value of the animation, if `random`
property is set this will be ignored | -| `animation.sync` | `boolean` | `true` / `false` | Unless `animation.startValue` is set to `random`, when `sync` is
toggled `true`, particles will change size simultaneously for
their entire duration; when `false`, particles begin changing
size from their time of appearance, but independently
of one another. | +Controls the visual size of particles, including animated grow/shrink effects. + +## Properties + +| Key | Type | Example | Notes | +| ---------------------- | ------------------ | -------------------------- | -------------------------------------------------------- | +| `value` | `number` / `range` | `4` / `{ min: 1, max: 8 }` | Base radius in pixels | +| `animation.enable` | `boolean` | `true` / `false` | Animates size over time | +| `animation.speed` | `number` | `3` | Rate of change as a function of other size values | +| `animation.startValue` | `string` | `min` / `max` / `random` | Starting point of the animation | +| `animation.sync` | `boolean` | `true` / `false` | When `true`, all particles resize in sync | +| `animation.destroy` | `string` | `min` / `max` / `none` | Destroys the particle when size reaches the chosen bound | + +## Quick examples + +### Fixed size + +```json +{ + "size": { + "value": 4 + } +} +``` + +### Random size per particle + +```json +{ + "size": { + "value": { "min": 1, "max": 6 } + } +} +``` + +### Pulsing effect (grow and shrink) + +```json +{ + "size": { + "value": { "min": 2, "max": 8 }, + "animation": { + "enable": true, + "speed": 2, + "startValue": "random", + "sync": false + } + } +} +``` + +### Shrink to destruction (e.g. for emitter-based effects) + +```json +{ + "size": { + "value": 6, + "animation": { + "enable": true, + "speed": 1, + "startValue": "max", + "destroy": "min" + } + } +} +``` + +## Common pitfalls + +- Using `destroy: "min"` without an emitter to replenish particles will result in an empty canvas +- `animation.sync: true` is ignored when `startValue` is `random` +- Retina devices multiply `value` by `devicePixelRatio`; combine with `detectRetina: true` for consistent results + +## Related docs + +- Particles root: [Particles](../Particles.md) +- Opacity (same animation shape): [Opacity](./Opacity.md) +- Options root: [Options](../../Options.md) diff --git a/markdown/Options/Particles/Stroke.md b/markdown/Options/Particles/Stroke.md index c7bc1dd4085..e2728cd1bd3 100644 --- a/markdown/Options/Particles/Stroke.md +++ b/markdown/Options/Particles/Stroke.md @@ -1,6 +1,23 @@ # Particles Stroke -| key | option type | example | notes | -| ------- | -------------- | ------- | ----------------------------------------------------------------------- | -| `width` | `number` | `2` | | -| `color` | `color object` | | This `color` object is the same described here {@link IAnimatableColor} | +Defines the outline drawn around particle shapes. + +## Properties + +| Key | Type | Example | Notes | +| ------- | -------------- | ------- | ------------------------------------------ | +| `width` | `number` | `2` | Stroke width in pixels | +| `color` | `color object` | | Stroke color, see {@link IAnimatableColor} | + +## Quick example + +```json +{ + "stroke": { + "width": 2, + "color": { + "value": "#ffffff" + } + } +} +``` diff --git a/markdown/Options/Particles/Tilt.md b/markdown/Options/Particles/Tilt.md index ee829ec1958..684a394f710 100644 --- a/markdown/Options/Particles/Tilt.md +++ b/markdown/Options/Particles/Tilt.md @@ -1,10 +1,31 @@ # Particles Tilt -| key | option type | example | notes | -| ------------------ | ------------------ | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `enable` | `boolean` | `true` / `false` | | -| `value` | `number` / `range` | `0` / `{ min: 1, max: 5 }` | angle in degrees | -| `direction` | `string` | `"clockwise"` / `"counter-clockwise"` / `"random"` | | -| `animation.enable` | `boolean` | `true` / `false` | | -| `animation.speed` | `number` | `5` | Describes the rate at which a particle will turn as a function
of `value` inputs | -| `animation.sync` | `boolean` | `true` / `false` | When `sync` is toggled `true`, particles generated will turn in
time with each other for their entire duration. However, when `sync` is
toggled `false`, particles generated begin turning at the set speed from
their time of appearance, but independently of one another. | +Applies tilt rotation to particle rendering. + +## Properties + +| Key | Type | Example | Notes | +| ------------------ | ------------------ | -------------------------------------------------- | ----------------------------------- | +| `enable` | `boolean` | `true` / `false` | Enables tilt effect | +| `value` | `number` / `range` | `0` / `{ min: 1, max: 5 }` | Base tilt angle in degrees | +| `direction` | `string` | `"clockwise"` / `"counter-clockwise"` / `"random"` | Tilt direction | +| `animation.enable` | `boolean` | `true` / `false` | Enables tilt animation | +| `animation.speed` | `number` | `5` | Tilt speed | +| `animation.sync` | `boolean` | `true` / `false` | `true`: synchronized tilt animation | + +## Quick example + +```json +{ + "tilt": { + "enable": true, + "value": { "min": 0, "max": 45 }, + "direction": "random", + "animation": { + "enable": true, + "speed": 20, + "sync": false + } + } +} +``` diff --git a/markdown/Options/Particles/Twinkle.md b/markdown/Options/Particles/Twinkle.md index de559c8d402..c5153f42a58 100644 --- a/markdown/Options/Particles/Twinkle.md +++ b/markdown/Options/Particles/Twinkle.md @@ -1,9 +1,33 @@ # Particles Twinkle -| key | option type | example | notes | -| --------------------- | -------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------ | -| `particles.enable` | `boolean` | `true` / `false` | | -| `particles.color` | `color object` | | This `color` object is the same described here {@link IColor}, this value is optional | -| `particles.frequency` | `number` | `0...1` | This value will be the comparison to `Math.random()` call, if the random value is greater the twinkle effect will be displayed | -| `particles.opacity` | `number` | `0...1` | | -| `lines` | `object` | | The same values of `particles` but applied to linked lines | +Adds random blinking effects to particles and links. + +## Properties + +| Key | Type | Example | Notes | +| --------------------- | -------------- | ---------------- | ------------------------------------------------ | +| `particles.enable` | `boolean` | `true` / `false` | Enables particle twinkle | +| `particles.color` | `color object` | | Optional twinkle color, see {@link IColor} | +| `particles.frequency` | `number` | `0...1` | Probability threshold for twinkle per frame | +| `particles.opacity` | `number` | `0...1` | Twinkle opacity | +| `lines` | `object` | | Same properties as `particles`, applied to links | + +## Quick example + +```json +{ + "twinkle": { + "particles": { + "enable": true, + "frequency": 0.05, + "opacity": 1, + "color": { + "value": "#ffffff" + } + }, + "lines": { + "enable": false + } + } +} +``` diff --git a/markdown/Options/Particles/Wobble.md b/markdown/Options/Particles/Wobble.md index 5990216196a..2f65d8c85bd 100644 --- a/markdown/Options/Particles/Wobble.md +++ b/markdown/Options/Particles/Wobble.md @@ -1,7 +1,29 @@ # Particles Wobble -| key | option type | example | notes | -| ---------- | ------------------ | -------------------------- | --------------------------------------------------------------------------------------------------------------------- | -| `distance` | `number` / `range` | `0` / `{ min: 1, max: 5 }` | | -| `enable` | `boolean` | `true` / `false` | | -| `speed` | `number` / `range` | `0` / `{ min: 1, max: 5 }` | Describes the rate of travel of a particle progressing along the
curve defined by other values in this property. | +Applies oscillating movement on top of normal particle motion. + +## Properties + +| Key | Type | Example | Notes | +| ---------- | ------------------ | -------------------------- | --------------------- | +| `enable` | `boolean` | `true` / `false` | Enables wobble effect | +| `distance` | `number` / `range` | `0` / `{ min: 1, max: 5 }` | Oscillation amplitude | +| `speed` | `number` / `range` | `0` / `{ min: 1, max: 5 }` | Oscillation speed | + +## Quick example + +```json +{ + "wobble": { + "enable": true, + "distance": { + "min": 2, + "max": 6 + }, + "speed": { + "min": 4, + "max": 10 + } + } +} +``` diff --git a/markdown/Options/Particles/ZIndex.md b/markdown/Options/Particles/ZIndex.md index 1ca57f8c957..b6d2331329c 100644 --- a/markdown/Options/Particles/ZIndex.md +++ b/markdown/Options/Particles/ZIndex.md @@ -1,8 +1,28 @@ # Particles zIndex -| key | option type | example | notes | -| -------------- | ------------------- | ---------------------------------- | --------------------------------------------------------------- | -| `value` | `number` / `object` | `0...100` / `{ min: 0, max: 100 }` | Defaults to 0. | -| `opacityRate` | `number` | `2` | The rate with which the z-index alters the particle's opacity. | -| `velocityRate` | `number` | `-10` | The rate with which the z-index alters the particle's velocity. | -| `sizeRate` | `number` | `5` | The rate with which the z-index alters the particle's size. | +Controls how particle layering affects opacity, velocity, and size. + +## Properties + +| Key | Type | Example | Notes | +| -------------- | ------------------ | ---------------------------------- | ---------------------------------------- | +| `value` | `number` / `range` | `0...100` / `{ min: 0, max: 100 }` | Base z-layer value | +| `opacityRate` | `number` | `2` | Multiplier applied to opacity by zIndex | +| `velocityRate` | `number` | `-10` | Multiplier applied to velocity by zIndex | +| `sizeRate` | `number` | `5` | Multiplier applied to size by zIndex | + +## Quick example + +```json +{ + "zIndex": { + "value": { + "min": 0, + "max": 50 + }, + "opacityRate": 1, + "velocityRate": -2, + "sizeRate": 2 + } +} +``` diff --git a/markdown/Options/Plugins/Absorbers.md b/markdown/Options/Plugins/Absorbers.md index 00495e0bc03..d6e531ce39f 100644 --- a/markdown/Options/Plugins/Absorbers.md +++ b/markdown/Options/Plugins/Absorbers.md @@ -1,10 +1,36 @@ # Absorbers -| key | option type | example | notes | -| -------------- | ------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------- | -| `color` | `color object` | | This `color` object is the same described here {@link IColor} | -| `opacity` | `number` | `0...1` | | -| `position` | `object` | `{ "x": 50, "y": 50 }` | The position specified is not absolute, it will be used as a percent value of the canvas size. | -| `size.density` | `number` | `5` | The higher the value, the more the particles are attracted | -| `size.limit` | `number` | `100` | The absorber max radius, this value is optional | -| `size.value` | `number` / `object` | `50` / `{ min: 10, max: 50 }` | The absorber radius | +Defines absorber entities that pull nearby particles and can consume them. + +## Properties + +| Key | Type | Example | Notes | +| -------------- | ------------------ | ----------------------------- | ---------------------------------- | +| `color` | `color object` | | Absorber color, see {@link IColor} | +| `opacity` | `number` | `0...1` | Absorber opacity | +| `position` | `object` | `{ "x": 50, "y": 50 }` | Position in canvas percent values | +| `size.value` | `number` / `range` | `50` / `{ min: 10, max: 50 }` | Absorber radius | +| `size.density` | `number` | `5` | Attraction intensity | +| `size.limit` | `number` | `100` | Maximum absorber radius | + +## Quick example + +```json +{ + "absorbers": { + "color": { + "value": "#f59e0b" + }, + "opacity": 0.7, + "position": { + "x": 50, + "y": 50 + }, + "size": { + "value": 30, + "density": 6, + "limit": 120 + } + } +} +``` diff --git a/markdown/Options/Plugins/Emitters.md b/markdown/Options/Plugins/Emitters.md index b30cdbcac34..9ecf5227905 100644 --- a/markdown/Options/Plugins/Emitters.md +++ b/markdown/Options/Plugins/Emitters.md @@ -1,15 +1,47 @@ # Emitters -| key | option type | example | notes | -| --------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | -| `direction` | `string` | `"none"`
`"top"`
`"top-right"`
`"right"`
`"bottom-right"`
`"bottom"`
`"bottom-left"`
`"left"`
`"top-left"` | The generated particles direction | -| `life.count` | `number` | `1` | The emitter number of times will appear | -| `life.duration` | `number` | `5` | The emitter life duration, in seconds | -| `life.delay` | `number` | `0.1` | The emitter delay between any appearance | -| `particles` | `object` | | See Particles options here {@link IParticlesOptions} | -| `position` | `object` | `{ "x": 50, "y": 50 }` | The position specified is not absolute, it will be used as a percent value of the canvas size. | -| `size.width` | `number` | `10` | | -| `size.height` | `number` | `10` | | -| `size.mode` | `string` | `"precise"` / `"percent"` | Specify how to use the size values, `precise` uses pixels, `percent` will be calculated on canvas size | -| `rate.quantity` | `number` | `1` | The particles generated everytime the rate event occurs | -| `rate.delay` | `number` | `0.1` | The rate event event delay time, in seconds | +Defines particle emitters that continuously or periodically spawn particles. + +## Properties + +| Key | Type | Example | Notes | +| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- | +| `direction` | `string` | `"none"`, `"top"`, `"top-right"`, `"right"`, `"bottom-right"`, `"bottom"`, `"bottom-left"`, `"left"`, `"top-left"` | Spawn direction | +| `life.count` | `number` | `1` | Number of emitter cycles | +| `life.duration` | `number` | `5` | Emitter active duration (seconds) | +| `life.delay` | `number` | `0.1` | Delay between cycles (seconds) | +| `particles` | `object` | | Spawned particle options, see {@link IParticlesOptions} | +| `position` | `object` | `{ "x": 50, "y": 50 }` | Position in canvas percent values | +| `size.width` | `number` | `10` | Emitter area width | +| `size.height` | `number` | `10` | Emitter area height | +| `size.mode` | `string` | `"precise"` / `"percent"` | `precise`: pixels, `percent`: relative to canvas size | +| `rate.quantity` | `number` | `1` | Particles generated per emission | +| `rate.delay` | `number` | `0.1` | Delay between emissions (seconds) | + +## Quick example + +```json +{ + "emitters": { + "direction": "top", + "position": { + "x": 50, + "y": 90 + }, + "size": { + "width": 40, + "height": 0, + "mode": "percent" + }, + "rate": { + "quantity": 4, + "delay": 0.15 + }, + "particles": { + "move": { + "speed": 2 + } + } + } +} +``` diff --git a/markdown/Options/Plugins/Infection.md b/markdown/Options/Plugins/Infection.md index 02076fccdf4..d341cb1f6b6 100644 --- a/markdown/Options/Plugins/Infection.md +++ b/markdown/Options/Plugins/Infection.md @@ -1,19 +1,47 @@ # Infection -| key | option type | example | notes | -| ------------ | ----------- | ---------------- | ----------------------------------------------------------------------------------- | -| `cure` | `boolean` | `true` / `false` | if the infection can be cured, bringing back the particle to its normal state | -| `delay` | `number` | `1` | the "symptoms" delay, after how many seconds the infected particle change its state | -| `enable` | `boolean` | `true` / `false` | | -| `infections` | `number` | `1` | how many particles are infected at startup | -| `stages` | `array` | | | +Configures infection-like propagation between particles. -## Infection Stage +## Properties -| key | option type | example | notes | -| --------------- | -------------- | ------- | ----------------------------------------------------------------------------------- | -| `color` | `color object` | | This `color` object is the same described here {@link IColor} | -| `radius` | `number` | `1` | an outer radius for spreading the infection without touch | -| `rate` | `number` | `1` | chances of infecting other particles | -| `duration` | `number` | `1` | how many seconds does the stage should last | -| `infectedStage` | `number` | `0` | which stage should be set when a particle will be infected by another at this stage | +| Key | Type | Example | Notes | +| ------------ | --------- | ---------------- | --------------------------------------- | +| `enable` | `boolean` | `true` / `false` | Enables infection mode | +| `infections` | `number` | `1` | Number of particles infected at startup | +| `delay` | `number` | `1` | Delay in seconds before symptoms apply | +| `cure` | `boolean` | `true` / `false` | If infected particles can recover | +| `stages` | `array` | | Infection stages sequence | + +## Infection stage properties + +| Key | Type | Example | Notes | +| --------------- | -------------- | ------- | --------------------------------------- | +| `color` | `color object` | | Stage color, see {@link IColor} | +| `radius` | `number` | `1` | Infection spread radius | +| `rate` | `number` | `1` | Infection chance multiplier | +| `duration` | `number` | `1` | Stage duration in seconds | +| `infectedStage` | `number` | `0` | Next stage index for infected particles | + +## Quick example + +```json +{ + "infection": { + "enable": true, + "infections": 2, + "delay": 0.5, + "cure": true, + "stages": [ + { + "color": { + "value": "#22c55e" + }, + "radius": 1, + "rate": 0.3, + "duration": 2, + "infectedStage": 0 + } + ] + } +} +``` diff --git a/markdown/Options/Plugins/PolygonMask.md b/markdown/Options/Plugins/PolygonMask.md index 0cb25f893a7..932771f999f 100644 --- a/markdown/Options/Plugins/PolygonMask.md +++ b/markdown/Options/Plugins/PolygonMask.md @@ -1,13 +1,44 @@ # Polygon Mask -| key | option type | example | notes | -| ---------------- | -------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | --- | -| `enable` | `boolean` | `true` / `false` | | -| `draw.enable` | `boolean` | `true` / `false` | | -| `draw.lineWidth` | `number` | `0.5` | | -| `draw.lineColor` | `color object` | | This `color` object is the same described here {@link IColor} | | -| `position` | `object` | `{ "x": 50, "y": 50 }` | The position specified is not absolute, it will be used as a percent value. | -| `scale` | `number` | 1 | | -| `type` | `string` | `none`
`inside`
`outside`
`inline` | | -| `move.radius` | `number` | `10` | | -| `url` | `string` | `demo/svg/deer.svg` | this file will be downloaded with an ajax request, if it won't load you have some **XSS** issues | +Constrains particles to a polygon/SVG shape and optionally draws its outline. + +## Properties + +| Key | Type | Example | Notes | +| ---------------- | -------------- | --------------------------------------------- | ---------------------------------- | +| `enable` | `boolean` | `true` / `false` | Enables polygon mask | +| `url` | `string` | `"demo/svg/deer.svg"` | SVG source URL | +| `type` | `string` | `"none"`, `"inside"`, `"outside"`, `"inline"` | Particle placement mode | +| `position` | `object` | `{ "x": 50, "y": 50 }` | Position in canvas percent values | +| `scale` | `number` | `1` | Polygon scale factor | +| `move.radius` | `number` | `10` | Movement radius along inline paths | +| `draw.enable` | `boolean` | `true` / `false` | Draws polygon outline | +| `draw.lineWidth` | `number` | `0.5` | Outline width | +| `draw.lineColor` | `color object` | | Outline color, see {@link IColor} | + +## Quick example + +```json +{ + "polygon": { + "enable": true, + "url": "demo/svg/deer.svg", + "type": "inline", + "position": { + "x": 50, + "y": 50 + }, + "scale": 1, + "move": { + "radius": 8 + }, + "draw": { + "enable": false, + "lineWidth": 0.5, + "lineColor": { + "value": "#ffffff" + } + } + } +} +``` diff --git a/markdown/Options/Themes.md b/markdown/Options/Themes.md index 397fd025f95..cdba47454e6 100644 --- a/markdown/Options/Themes.md +++ b/markdown/Options/Themes.md @@ -1,33 +1,87 @@ # Theme Options -- [Theme Options](#theme-options) - - [Default](#default) - - [Mode](#mode) - - [Value](#value) - - [Name](#name) - - [Options](#options) +Allows defining multiple named themes (light/dark/any) that can be switched at runtime via `container.loadTheme(name)`. -## Default +## Structure -- [mode](#mode) -- [value](#value) +```json +{ + "themes": [ + { + "name": "dark", + "default": { + "value": true, + "mode": "dark" + }, + "options": { + "background": { "color": "#0d1117" }, + "particles": { "color": { "value": "#ffffff" } } + } + }, + { + "name": "light", + "default": { + "value": true, + "mode": "light" + }, + "options": { + "background": { "color": "#ffffff" }, + "particles": { "color": { "value": "#000000" } } + } + } + ] +} +``` -### Mode +## Properties -Values accepted +### `name` -- `"any"` -- `"dark"` -- `"light"` +A string identifier used to reference the theme in `container.loadTheme("dark")`. -### Value +### `default` -If set to `true` this theme will be the default one for the specified mode, the last one set to default will be used if more than one are set. +Controls whether and when this theme is applied automatically. -## Name +| Key | Type | Values | Notes | +| --------------- | --------- | ------------------------------ | ------------------------------------------------------- | +| `default.value` | `boolean` | `true` / `false` | If `true`, this is the default theme for the given mode | +| `default.mode` | `string` | `"any"` / `"dark"` / `"light"` | Applies when the OS/browser reports this color scheme | -The theme name used to change the theme using the {@link Container.loadTheme} function +- `"dark"` — applied when `prefers-color-scheme: dark` is detected +- `"light"` — applied when `prefers-color-scheme: light` is detected +- `"any"` — applied regardless of system preference -## Options +If more than one theme sets `default.value: true` for the same `mode`, the last one wins. -This object is the entire {@link Options | options } object +### `options` + +A partial {@link Options} object. Only the properties you specify will override the base config — everything else remains unchanged. + +## Switching themes at runtime + +```javascript +const container = await tsParticles.load({ + id: "tsparticles", + options: { + /* ... */ + }, +}); + +// Switch to a named theme +container.loadTheme("dark"); + +// Reset to the default theme for the current mode +container.loadTheme(undefined); +``` + +## Common pitfalls + +- Defining two themes with `default.value: true` for the same `mode` — only the last one is used +- Passing a `name` that was not registered in `themes` to `loadTheme()` — nothing changes +- Setting complex nested overrides in `options` and expecting deep merge — only specified keys are overridden + +## Related docs + +- Container runtime API: [Container](../Container.md) +- Options root: [Options](../Options.md) diff --git a/markdown/Pages/index.md b/markdown/Pages/index.md index 3a7845af0e0..0c942001bc9 100644 --- a/markdown/Pages/index.md +++ b/markdown/Pages/index.md @@ -1,3 +1,129 @@ # tsParticles -## Index Page +Quick guide to choose the right package, find the right option reference, and start from presets, palettes, or ready-made configs in a few minutes. + +## Quick checklist + +If this is your first time with tsParticles: + +1. Install `@tsparticles/engine` +2. Pick one runtime path: + - `@tsparticles/slim` for most production websites and apps + - `@tsparticles/all` for prototypes, playgrounds, and full feature coverage + - only the packages you need if you want a minimal custom build +3. Load your chosen bundle once +4. Start with one of these inputs: + - manual options + - a ready-made config from `@tsparticles/configs` + - an official preset from the `tsparticles/presets` repository + +## Minimal start example + +```ts +import { tsParticles } from "@tsparticles/engine"; +import { loadSlim } from "@tsparticles/slim"; + +await loadSlim(tsParticles); + +await tsParticles.load({ + id: "tsparticles", + options: { + background: { + color: "#0d1117", + }, + particles: { + number: { + value: 60, + }, + move: { + enable: true, + speed: 1.2, + }, + size: { + value: { min: 1, max: 3 }, + }, + }, + }, +}); +``` + +## Choose your quick-start path + +- **I need a production-ready default**: `@tsparticles/slim` +- **I need only core plus custom plugins**: `@tsparticles/engine` +- **I need every feature for quick prototyping**: `@tsparticles/all` +- **I want a ready visual starting point**: use `@tsparticles/configs` or an official preset first + +## Quick documentation map + +- Root options: [Options](../Options.md) +- Color formats and values: [Color](../Color.md) +- Runtime container management: [Container](../Container.md) +- Plugins, custom shapes, custom presets: [Plugins](../Plugins.md) +- Migration from particles.js: [pjsMigration](../pjsMigration.md) + +## Detailed option guides + +- Canvas and global behavior: [Background](../Options/Background.md), [Background Mask](../Options/BackgroundMask.md), [Full Screen](../Options/FullScreen.md), [Motion](../Options/Motion.md) +- Interactivity: [Interactivity](../Options/Interactivity.md), [Click](../Options/Interactivity/Click.md), [Hover](../Options/Interactivity/Hover.md), [Div](../Options/Interactivity/Div.md) +- Particle behavior: [Particles](../Options/Particles.md), [Color](../Options/Particles/Color.md), [Collisions](../Options/Particles/Collisions.md), [Life](../Options/Particles/Life.md), [Orbit](../Options/Particles/Orbit.md) +- Plugin-driven options: [Absorbers](../Options/Plugins/Absorbers.md), [Emitters](../Options/Plugins/Emitters.md), [Infection](../Options/Plugins/Infection.md), [Polygon Mask](../Options/Plugins/PolygonMask.md) + +## Ready-made starting sources + +### Configs (`@tsparticles/configs`) + +Use configs when you want a concrete example object you can inspect and modify directly. + +- Package README: