Skip to content

Readme update #65

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Dec 10, 2023
Merged

Readme update #65

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
854c72c
build: updated readme
matteobruni Dec 10, 2023
7564451
Merge branch 'main' into dev
matteobruni Dec 10, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
276 changes: 166 additions & 110 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,12 +22,26 @@ or
yarn add @tsparticles/react
```

### TypeScript Installation

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

or

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

[@tsparticles/engine](https://npmjs.com/package/@tsparticles/engine) is the core package for [tsParticles](https://particles.js.org), it contains useful types like `ISourceOptions`, `Engine` or `Container`.

### create-react-app

Starting from version 1.17.0 there are two official `create-react-app` templates:

- `cra-template-particles`: Simple ReactJS template with full screen particles, using JavaScript
- `cra-template-particles-typescript`: Simple ReactJS template with full screen particles, using TypeScript
- `cra-template-particles`: Simple ReactJS template with full screen particles, using JavaScript
- `cra-template-particles-typescript`: Simple ReactJS template with full screen particles, using TypeScript

You can simply install them using the `create-react-app` command like this:

Expand All @@ -47,95 +61,44 @@ $ create-react-app your_app --template particles-typescript

Examples:

#### Remote url

##### JavaScript support - url

```jsx
import { useCallback } from "react";
import Particles from "@tsparticles/react";
//import { loadFull } from "tsparticles"; // if you are going to use `loadFull`, install the "tsparticles" package too.
import { loadSlim } from "@tsparticles/slim"; // if you are going to use `loadSlim`, install the "@tsparticles/slim" package too.

const App = () => {
const particlesInit = useCallback(async engine => {
console.log(engine);
// you can initiate the tsParticles instance (engine) here, adding custom shapes or presets
// this loads the tsparticles package bundle, it's the easiest method for getting everything ready
// starting from v2 you can add only the features you need reducing the bundle size
//await loadFull(engine);
await loadSlim(engine);
}, []);

const particlesLoaded = useCallback(async container => {
console.log(container);
}, []);

return (
<Particles id="tsparticles" url="http://foo.bar/particles.json" init={particlesInit} loaded={particlesLoaded} />
);
};
```

##### TypeScript support - url

```typescript jsx
import { useCallback } from "react";
import Particles from "@tsparticles/react";
import type { Container, Engine } from "@tsparticles/engine";
//import { loadFull } from "tsparticles"; // if you are going to use `loadFull`, install the "tsparticles" package too.
import { loadSlim } from "@tsparticles/slim"; // if you are going to use `loadSlim`, install the "@tsparticles/slim" package too.

const App = () => {
const particlesInit = useCallback(async (engine: Engine) => {
console.log(engine);

// you can initialize the tsParticles instance (engine) here, adding custom shapes or presets
// this loads the tsparticles package bundle, it's the easiest method for getting everything ready
// starting from v2 you can add only the features you need reducing the bundle size
//await loadFull(engine);
await loadSlim(engine);
}, []);

const particlesLoaded = useCallback(async (container: Container | undefined) => {
console.log(container);
}, []);

return (
<Particles id="tsparticles" url="http://foo.bar/particles.json" init={particlesInit} loaded={particlesLoaded} />
);
};
```

#### Options object

##### JavaScript support - object

```jsx
import { useCallback } from "react";
import Particles from "@tsparticles/react";
//import { loadFull } from "tsparticles"; // if you are going to use `loadFull`, install the "tsparticles" package too.
import { useCallback, useEffect, useState } from "react";
import Particles, { initParticlesEngine } from "@tsparticles/react";
// import { loadAll } from "@/tsparticles/all"; // if you are going to use `loadAll`, install the "@tsparticles/all" package too.
// import { loadFull } from "tsparticles"; // if you are going to use `loadFull`, install the "tsparticles" package too.
import { loadSlim } from "@tsparticles/slim"; // if you are going to use `loadSlim`, install the "@tsparticles/slim" package too.
// import { loadBasic } from "@tsparticles/basic"; // if you are going to use `loadBasic`, install the "@tsparticles/basic" package too.

const App = () => {
const particlesInit = useCallback(async engine => {
console.log(engine);
// you can initiate the tsParticles instance (engine) here, adding custom shapes or presets
// this loads the tsparticles package bundle, it's the easiest method for getting everything ready
// starting from v2 you can add only the features you need reducing the bundle size
//await loadFull(engine);
await loadSlim(engine);
const [ init, setInit ] = useState(false);

// this should be run only once per application lifetime
useEffect(() => {
initParticlesEngine(async (engine) => {
// you can initiate the tsParticles instance (engine) here, adding custom shapes or presets
// this loads the tsparticles package bundle, it's the easiest method for getting everything ready
// starting from v2 you can add only the features you need reducing the bundle size
//await loadAll(engine);
//await loadFull(engine);
await loadSlim(engine);
//await loadBasic(engine);
}).then(() => {
setInit(true);
});
}, []);

const particlesLoaded = useCallback(async container => {
const particlesLoaded = (container) => {
console.log(container);
}, []);
};

return (
<Particles
{ init && <Particles
id="tsparticles"
init={particlesInit}
loaded={particlesLoaded}
particlesLoaded={particlesLoaded}
options={{
background: {
color: {
Expand Down Expand Up @@ -206,38 +169,49 @@ const App = () => {
detectRetina: true,
}}
/>
);
}
)
;
};
```

##### TypeScript support - object

```typescript jsx
import { useCallback } from "react";
```tsx
import { useCallback, useEffect, useState } from "react";
import Particles, { initParticlesEngine } from "@tsparticles/react";
import type { Container, Engine } from "@tsparticles/engine";
import Particles from "@tsparticles/react";
//import { loadFull } from "tsparticles"; // if you are going to use `loadFull`, install the "tsparticles" package too.
// import { loadAll } from "@/tsparticles/all"; // if you are going to use `loadAll`, install the "@tsparticles/all" package too.
// import { loadFull } from "tsparticles"; // if you are going to use `loadFull`, install the "tsparticles" package too.
import { loadSlim } from "@tsparticles/slim"; // if you are going to use `loadSlim`, install the "@tsparticles/slim" package too.
// import { loadBasic } from "@tsparticles/basic"; // if you are going to use `loadBasic`, install the "@tsparticles/basic" package too.

const App = () => {
const particlesInit = useCallback(async (engine: Engine) => {
console.log(engine);

// you can initialize the tsParticles instance (engine) here, adding custom shapes or presets
// this loads the tsparticles package bundle, it's the easiest method for getting everything ready
// starting from v2 you can add only the features you need reducing the bundle size
//await loadFull(engine);
await loadSlim(engine);
const [ init, setInit ] = useState(false);

// this should be run only once per application lifetime
useEffect(() => {
initParticlesEngine(async (engine) => {
// you can initiate the tsParticles instance (engine) here, adding custom shapes or presets
// this loads the tsparticles package bundle, it's the easiest method for getting everything ready
// starting from v2 you can add only the features you need reducing the bundle size
//await loadAll(engine);
//await loadFull(engine);
await loadSlim(engine);
//await loadBasic(engine);
}).then(() => {
setInit(true);
});
}, []);

const particlesLoaded = useCallback(async (container: Container | undefined) => {
const particlesLoaded = (container) => {
console.log(container);
}, []);
};

return (
<Particles
{ init && <Particles
id="tsparticles"
init={particlesInit}
loaded={particlesLoaded}
particlesLoaded={particlesLoaded}
options={{
background: {
color: {
Expand Down Expand Up @@ -308,29 +282,111 @@ const App = () => {
detectRetina: true,
}}
/>
);
}
)
;
};
```

#### Remote url

##### JavaScript support - url

```jsx
import { useCallback, useEffect, useState } from "react";
import Particles, { initParticlesEngine } from "@tsparticles/react";
// import { loadAll } from "@/tsparticles/all"; // if you are going to use `loadAll`, install the "@tsparticles/all" package too.
// import { loadFull } from "tsparticles"; // if you are going to use `loadFull`, install the "tsparticles" package too.
import { loadSlim } from "@tsparticles/slim"; // if you are going to use `loadSlim`, install the "@tsparticles/slim" package too.
// import { loadBasic } from "@tsparticles/basic"; // if you are going to use `loadBasic`, install the "@tsparticles/basic" package too.

const App = () => {
const [ init, setInit ] = useState(false);

// this should be run only once per application lifetime
useEffect(() => {
initParticlesEngine(async (engine) => {
// you can initiate the tsParticles instance (engine) here, adding custom shapes or presets
// this loads the tsparticles package bundle, it's the easiest method for getting everything ready
// starting from v2 you can add only the features you need reducing the bundle size
//await loadAll(engine);
//await loadFull(engine);
await loadSlim(engine);
//await loadBasic(engine);
}).then(() => {
setInit(true);
});
}, []);

const particlesLoaded = (container) => {
console.log(container);
};

return (
{ init && <Particles id="tsparticles" url="http://foo.bar/particles.json" particlesLoaded={particlesLoaded}/>
}
)
;
};
```

##### TypeScript support - url

```tsx
import { useCallback, useEffect, useState } from "react";
import Particles, { initParticlesEngine } from "@tsparticles/react";
import type { Container, Engine } from "@tsparticles/engine";
// import { loadAll } from "@/tsparticles/all"; // if you are going to use `loadAll`, install the "@tsparticles/all" package too.
// import { loadFull } from "tsparticles"; // if you are going to use `loadFull`, install the "tsparticles" package too.
import { loadSlim } from "@tsparticles/slim"; // if you are going to use `loadSlim`, install the "@tsparticles/slim" package too.
// import { loadBasic } from "@tsparticles/basic"; // if you are going to use `loadBasic`, install the "@tsparticles/basic" package too.

const App = () => {
const [ init, setInit ] = useState(false);

// this should be run only once per application lifetime
useEffect(() => {
initParticlesEngine(async (engine) => {
// you can initiate the tsParticles instance (engine) here, adding custom shapes or presets
// this loads the tsparticles package bundle, it's the easiest method for getting everything ready
// starting from v2 you can add only the features you need reducing the bundle size
//await loadAll(engine);
//await loadFull(engine);
await loadSlim(engine);
//await loadBasic(engine);
}).then(() => {
setInit(true);
});
}, []);

const particlesLoaded = (container) => {
console.log(container);
};

return (
{ init && <Particles id="tsparticles" url="http://foo.bar/particles.json" particlesLoaded={particlesLoaded}/>
}
)
;
};
```

### Props

| Prop | Type | Definition |
| --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | string | The id of the element. |
| width | string | The width of the canvas. |
| height | string | The height of the canvas. |
| options | object | The options of the particles instance. |
| url | string | The remote options url, called using an AJAX request |
| style | object | The style of the canvas element. |
| className | string | The class name of the canvas wrapper. |
| canvasClassName | string | the class name of the canvas. |
| container | object | The instance of the [particles container](https://particles.js.org/docs/classes/tsParticles_Engine.Core_Container.Container.html) |
| init | function | This function is called after the tsParticles instance initialization, the instance is the parameter and you can load custom presets or shapes here |
| loaded | function | This function is called when particles are correctly loaded in canvas, the current container is the parameter and you can customize it here |
| Prop | Type | Definition |
|-----------|--------|------------------------------------------------------|
| id | string | The id of the element. |
| width | string | The width of the canvas. |
| height | string | The height of the canvas. |
| options | object | The options of the particles instance. |
| url | string | The remote options url, called using an AJAX request |
| style | object | The style of the canvas element. |
| className | string | The class name of the canvas wrapper. |

#### particles.json

Find all configuration options [here](https://particles.js.org/docs/interfaces/tsParticles_Engine.Options_Interfaces_IOptions.IOptions.html).
Find all configuration
options [here](https://particles.js.org/docs/interfaces/tsParticles_Engine.Options_Interfaces_IOptions.IOptions.html).

You can find sample configurations [here](https://github.com/tsparticles/tsparticles/tree/main/utils/configs/src) 📖

Expand Down