@tsparticles/engine/README.md

Easily create highly customizable particle, confetti and fireworks animations and use them as animated backgrounds for your website. Ready to use components available also for React, Vue.js (2.x and 3.x), Angular, Svelte, jQuery, Preact, Riot.js, Inferno.

[![banner](https://particles.js.org/images/banner2.png)](https://particles.js.org)

# tsParticles Engine

[![jsDelivr](https://data.jsdelivr.com/v1/package/npm/@tsparticles/engine/badge)](https://www.jsdelivr.com/package/npm/@tsparticles/engine)
[![npmjs](https://badge.fury.io/js/@tsparticles/engine.svg)](https://www.npmjs.com/package/@tsparticles/engine)
[![npmjs](https://img.shields.io/npm/dt/@tsparticles/engine)](https://www.npmjs.com/package/@tsparticles/engine) [![GitHub Sponsors](https://img.shields.io/github/sponsors/matteobruni)](https://github.com/sponsors/matteobruni)

[tsParticles](https://github.com/tsparticles/tsparticles) is a lightweight TypeScript library for creating particles. Dependency free (\*), browser ready and compatible with React.js, Vue.js (2.x and 3.x), Angular, Svelte, jQuery, Preact, Inferno, Riot.js, Solid.js, and Web Components.

**This is the core engine package that all other features depend on.**

## Quick checklist

1. Install `@tsparticles/engine`
2. Initialize the engine instance in your code
3. Load additional plugins/shapes/updaters as needed
4. Use `tsParticles.load()` to apply particle configurations

## How to use it

### Installation

```shell
npm install @tsparticles/engine
```

or

```shell
yarn add @tsparticles/engine
```

or

```shell
pnpm install @tsparticles/engine
```

### Basic Usage

```javascript
import { tsParticles } from "@tsparticles/engine";

await tsParticles.load({
  id: "tsparticles",
  options: {
    particles: {
      number: {
        value: 80,
      },
      move: {
        enable: true,
        speed: 2,
      },
    },
  },
});
```

## Features

- **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

## Loading Additional Features

To extend the engine with more capabilities, load additional packages:

```javascript
import { tsParticles } from "@tsparticles/engine";
import { loadSlim } from "@tsparticles/slim"; // or other bundles

await loadSlim(tsParticles); // Load preset features

await tsParticles.load({
  id: "tsparticles",
  options: {
    // Your configuration here
  },
});
```

## Common pitfalls

- Loading plugins after calling `tsParticles.load(...)` may not work as expected
- Ensure all required peer packages are loaded before using their features
- Some shapes or updaters need their specific packages to be loaded

## Related docs

- Main documentation: <https://particles.js.org/docs/>
- Main repository: <https://github.com/tsparticles/tsparticles>
- Available bundles: <https://github.com/tsparticles/tsparticles#bundles>
- All options: <https://particles.js.org/docs/interfaces/tsParticles_Engine.Options_Interfaces_IOptions.IOptions.html>