From 854c72ce4066a89b39a9efcdad312b1c774fec4f Mon Sep 17 00:00:00 2001 From: Matteo Bruni <176620+matteobruni@users.noreply.github.com> Date: Sun, 10 Dec 2023 12:23:03 +0100 Subject: [PATCH] build: updated readme --- README.md | 276 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 166 insertions(+), 110 deletions(-) diff --git a/README.md b/README.md index 933632b..3a74d79 100644 --- a/README.md +++ b/README.md @@ -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: @@ -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 ( - - ); -}; -``` - -##### 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 ( - - ); -}; -``` - #### 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 ( - { 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 ( - { 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 && +} +) + ; +}; +``` + +##### 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 && +} +) + ; }; ``` ### 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) 📖