Skip to content

Commit 29a7a9a

Browse files
matteobrunimatteobruni
authored
Merge pull request #65 from tsparticles/dev
Readme update
2 parents 7b96390 + 7564451 commit 29a7a9a

File tree

1 file changed

+166
-110
lines changed

1 file changed

+166
-110
lines changed

‎README.md‎

Lines changed: 166 additions & 110 deletions
Original file line numberDiff line numberDiff line change
@@ -22,12 +22,26 @@ or
2222
yarn add @tsparticles/react
2323
```
2424

25+
### TypeScript Installation
26+
27+
```shell
28+
npm install @tsparticles/react @tsparticles/engine
29+
```
30+
31+
or
32+
33+
```shell
34+
yarn add @tsparticles/react @tsparticles/engine
35+
```
36+
37+
[@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`.
38+
2539
### create-react-app
2640

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

29-
- `cra-template-particles`: Simple ReactJS template with full screen particles, using JavaScript
30-
- `cra-template-particles-typescript`: Simple ReactJS template with full screen particles, using TypeScript
43+
- `cra-template-particles`: Simple ReactJS template with full screen particles, using JavaScript
44+
- `cra-template-particles-typescript`: Simple ReactJS template with full screen particles, using TypeScript
3145

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

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

4862
Examples:
4963

50-
#### Remote url
51-
52-
##### JavaScript support - url
53-
54-
```jsx
55-
import { useCallback } from "react";
56-
import Particles from "@tsparticles/react";
57-
//import { loadFull } from "tsparticles"; // if you are going to use `loadFull`, install the "tsparticles" package too.
58-
import { loadSlim } from "@tsparticles/slim"; // if you are going to use `loadSlim`, install the "@tsparticles/slim" package too.
59-
60-
const App = () => {
61-
const particlesInit = useCallback(async engine => {
62-
console.log(engine);
63-
// you can initiate the tsParticles instance (engine) here, adding custom shapes or presets
64-
// this loads the tsparticles package bundle, it's the easiest method for getting everything ready
65-
// starting from v2 you can add only the features you need reducing the bundle size
66-
//await loadFull(engine);
67-
await loadSlim(engine);
68-
}, []);
69-
70-
const particlesLoaded = useCallback(async container => {
71-
console.log(container);
72-
}, []);
73-
74-
return (
75-
<Particles id="tsparticles" url="http://foo.bar/particles.json" init={particlesInit} loaded={particlesLoaded} />
76-
);
77-
};
78-
```
79-
80-
##### TypeScript support - url
81-
82-
```typescript jsx
83-
import { useCallback } from "react";
84-
import Particles from "@tsparticles/react";
85-
import type { Container, Engine } from "@tsparticles/engine";
86-
//import { loadFull } from "tsparticles"; // if you are going to use `loadFull`, install the "tsparticles" package too.
87-
import { loadSlim } from "@tsparticles/slim"; // if you are going to use `loadSlim`, install the "@tsparticles/slim" package too.
88-
89-
const App = () => {
90-
const particlesInit = useCallback(async (engine: Engine) => {
91-
console.log(engine);
92-
93-
// you can initialize the tsParticles instance (engine) here, adding custom shapes or presets
94-
// this loads the tsparticles package bundle, it's the easiest method for getting everything ready
95-
// starting from v2 you can add only the features you need reducing the bundle size
96-
//await loadFull(engine);
97-
await loadSlim(engine);
98-
}, []);
99-
100-
const particlesLoaded = useCallback(async (container: Container | undefined) => {
101-
console.log(container);
102-
}, []);
103-
104-
return (
105-
<Particles id="tsparticles" url="http://foo.bar/particles.json" init={particlesInit} loaded={particlesLoaded} />
106-
);
107-
};
108-
```
109-
11064
#### Options object
11165

11266
##### JavaScript support - object
11367

11468
```jsx
115-
import { useCallback } from "react";
116-
import Particles from "@tsparticles/react";
117-
//import { loadFull } from "tsparticles"; // if you are going to use `loadFull`, install the "tsparticles" package too.
69+
import { useCallback, useEffect, useState } from "react";
70+
import Particles, { initParticlesEngine } from "@tsparticles/react";
71+
// import { loadAll } from "@/tsparticles/all"; // if you are going to use `loadAll`, install the "@tsparticles/all" package too.
72+
// import { loadFull } from "tsparticles"; // if you are going to use `loadFull`, install the "tsparticles" package too.
11873
import { loadSlim } from "@tsparticles/slim"; // if you are going to use `loadSlim`, install the "@tsparticles/slim" package too.
74+
// import { loadBasic } from "@tsparticles/basic"; // if you are going to use `loadBasic`, install the "@tsparticles/basic" package too.
11975

12076
const App = () => {
121-
const particlesInit = useCallback(async engine => {
122-
console.log(engine);
123-
// you can initiate the tsParticles instance (engine) here, adding custom shapes or presets
124-
// this loads the tsparticles package bundle, it's the easiest method for getting everything ready
125-
// starting from v2 you can add only the features you need reducing the bundle size
126-
//await loadFull(engine);
127-
await loadSlim(engine);
77+
const [ init, setInit ] = useState(false);
78+
79+
// this should be run only once per application lifetime
80+
useEffect(() => {
81+
initParticlesEngine(async (engine) => {
82+
// you can initiate the tsParticles instance (engine) here, adding custom shapes or presets
83+
// this loads the tsparticles package bundle, it's the easiest method for getting everything ready
84+
// starting from v2 you can add only the features you need reducing the bundle size
85+
//await loadAll(engine);
86+
//await loadFull(engine);
87+
await loadSlim(engine);
88+
//await loadBasic(engine);
89+
}).then(() => {
90+
setInit(true);
91+
});
12892
}, []);
12993

130-
const particlesLoaded = useCallback(async container => {
94+
const particlesLoaded = (container) => {
13195
console.log(container);
132-
}, []);
96+
};
13397

13498
return (
135-
<Particles
99+
{ init && <Particles
136100
id="tsparticles"
137-
init={particlesInit}
138-
loaded={particlesLoaded}
101+
particlesLoaded={particlesLoaded}
139102
options={{
140103
background: {
141104
color: {
@@ -206,38 +169,49 @@ const App = () => {
206169
detectRetina: true,
207170
}}
208171
/>
209-
);
172+
}
173+
)
174+
;
210175
};
211176
```
212177

213178
##### TypeScript support - object
214179

215-
```typescript jsx
216-
import { useCallback } from "react";
180+
```tsx
181+
import { useCallback, useEffect, useState } from "react";
182+
import Particles, { initParticlesEngine } from "@tsparticles/react";
217183
import type { Container, Engine } from "@tsparticles/engine";
218-
import Particles from "@tsparticles/react";
219-
//import { loadFull } from "tsparticles"; // if you are going to use `loadFull`, install the "tsparticles" package too.
184+
// import { loadAll } from "@/tsparticles/all"; // if you are going to use `loadAll`, install the "@tsparticles/all" package too.
185+
// import { loadFull } from "tsparticles"; // if you are going to use `loadFull`, install the "tsparticles" package too.
220186
import { loadSlim } from "@tsparticles/slim"; // if you are going to use `loadSlim`, install the "@tsparticles/slim" package too.
187+
// import { loadBasic } from "@tsparticles/basic"; // if you are going to use `loadBasic`, install the "@tsparticles/basic" package too.
221188

222189
const App = () => {
223-
const particlesInit = useCallback(async (engine: Engine) => {
224-
console.log(engine);
225-
226-
// you can initialize the tsParticles instance (engine) here, adding custom shapes or presets
227-
// this loads the tsparticles package bundle, it's the easiest method for getting everything ready
228-
// starting from v2 you can add only the features you need reducing the bundle size
229-
//await loadFull(engine);
230-
await loadSlim(engine);
190+
const [ init, setInit ] = useState(false);
191+
192+
// this should be run only once per application lifetime
193+
useEffect(() => {
194+
initParticlesEngine(async (engine) => {
195+
// you can initiate the tsParticles instance (engine) here, adding custom shapes or presets
196+
// this loads the tsparticles package bundle, it's the easiest method for getting everything ready
197+
// starting from v2 you can add only the features you need reducing the bundle size
198+
//await loadAll(engine);
199+
//await loadFull(engine);
200+
await loadSlim(engine);
201+
//await loadBasic(engine);
202+
}).then(() => {
203+
setInit(true);
204+
});
231205
}, []);
232206

233-
const particlesLoaded = useCallback(async (container: Container | undefined) => {
207+
const particlesLoaded = (container) => {
234208
console.log(container);
235-
}, []);
209+
};
210+
236211
return (
237-
<Particles
212+
{ init && <Particles
238213
id="tsparticles"
239-
init={particlesInit}
240-
loaded={particlesLoaded}
214+
particlesLoaded={particlesLoaded}
241215
options={{
242216
background: {
243217
color: {
@@ -308,29 +282,111 @@ const App = () => {
308282
detectRetina: true,
309283
}}
310284
/>
311-
);
285+
}
286+
)
287+
;
288+
};
289+
```
290+
291+
#### Remote url
292+
293+
##### JavaScript support - url
294+
295+
```jsx
296+
import { useCallback, useEffect, useState } from "react";
297+
import Particles, { initParticlesEngine } from "@tsparticles/react";
298+
// import { loadAll } from "@/tsparticles/all"; // if you are going to use `loadAll`, install the "@tsparticles/all" package too.
299+
// import { loadFull } from "tsparticles"; // if you are going to use `loadFull`, install the "tsparticles" package too.
300+
import { loadSlim } from "@tsparticles/slim"; // if you are going to use `loadSlim`, install the "@tsparticles/slim" package too.
301+
// import { loadBasic } from "@tsparticles/basic"; // if you are going to use `loadBasic`, install the "@tsparticles/basic" package too.
302+
303+
const App = () => {
304+
const [ init, setInit ] = useState(false);
305+
306+
// this should be run only once per application lifetime
307+
useEffect(() => {
308+
initParticlesEngine(async (engine) => {
309+
// you can initiate the tsParticles instance (engine) here, adding custom shapes or presets
310+
// this loads the tsparticles package bundle, it's the easiest method for getting everything ready
311+
// starting from v2 you can add only the features you need reducing the bundle size
312+
//await loadAll(engine);
313+
//await loadFull(engine);
314+
await loadSlim(engine);
315+
//await loadBasic(engine);
316+
}).then(() => {
317+
setInit(true);
318+
});
319+
}, []);
320+
321+
const particlesLoaded = (container) => {
322+
console.log(container);
323+
};
324+
325+
return (
326+
{ init && <Particles id="tsparticles" url="http://foo.bar/particles.json" particlesLoaded={particlesLoaded}/>
327+
}
328+
)
329+
;
330+
};
331+
```
332+
333+
##### TypeScript support - url
334+
335+
```tsx
336+
import { useCallback, useEffect, useState } from "react";
337+
import Particles, { initParticlesEngine } from "@tsparticles/react";
338+
import type { Container, Engine } from "@tsparticles/engine";
339+
// import { loadAll } from "@/tsparticles/all"; // if you are going to use `loadAll`, install the "@tsparticles/all" package too.
340+
// import { loadFull } from "tsparticles"; // if you are going to use `loadFull`, install the "tsparticles" package too.
341+
import { loadSlim } from "@tsparticles/slim"; // if you are going to use `loadSlim`, install the "@tsparticles/slim" package too.
342+
// import { loadBasic } from "@tsparticles/basic"; // if you are going to use `loadBasic`, install the "@tsparticles/basic" package too.
343+
344+
const App = () => {
345+
const [ init, setInit ] = useState(false);
346+
347+
// this should be run only once per application lifetime
348+
useEffect(() => {
349+
initParticlesEngine(async (engine) => {
350+
// you can initiate the tsParticles instance (engine) here, adding custom shapes or presets
351+
// this loads the tsparticles package bundle, it's the easiest method for getting everything ready
352+
// starting from v2 you can add only the features you need reducing the bundle size
353+
//await loadAll(engine);
354+
//await loadFull(engine);
355+
await loadSlim(engine);
356+
//await loadBasic(engine);
357+
}).then(() => {
358+
setInit(true);
359+
});
360+
}, []);
361+
362+
const particlesLoaded = (container) => {
363+
console.log(container);
364+
};
365+
366+
return (
367+
{ init && <Particles id="tsparticles" url="http://foo.bar/particles.json" particlesLoaded={particlesLoaded}/>
368+
}
369+
)
370+
;
312371
};
313372
```
314373

315374
### Props
316375

317-
| Prop | Type | Definition |
318-
| --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
319-
| id | string | The id of the element. |
320-
| width | string | The width of the canvas. |
321-
| height | string | The height of the canvas. |
322-
| options | object | The options of the particles instance. |
323-
| url | string | The remote options url, called using an AJAX request |
324-
| style | object | The style of the canvas element. |
325-
| className | string | The class name of the canvas wrapper. |
326-
| canvasClassName | string | the class name of the canvas. |
327-
| container | object | The instance of the [particles container](https://particles.js.org/docs/classes/tsParticles_Engine.Core_Container.Container.html) |
328-
| 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 |
329-
| 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 |
376+
| Prop | Type | Definition |
377+
|-----------|--------|------------------------------------------------------|
378+
| id | string | The id of the element. |
379+
| width | string | The width of the canvas. |
380+
| height | string | The height of the canvas. |
381+
| options | object | The options of the particles instance. |
382+
| url | string | The remote options url, called using an AJAX request |
383+
| style | object | The style of the canvas element. |
384+
| className | string | The class name of the canvas wrapper. |
330385

331386
#### particles.json
332387

333-
Find all configuration options [here](https://particles.js.org/docs/interfaces/tsParticles_Engine.Options_Interfaces_IOptions.IOptions.html).
388+
Find all configuration
389+
options [here](https://particles.js.org/docs/interfaces/tsParticles_Engine.Options_Interfaces_IOptions.IOptions.html).
334390

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

0 commit comments

Comments
 (0)