Configuration
This module provides a few options to customize its behavior.
Lazy-loading
By default, nuxt-particles lazy-loads the tsParticles library. This means that the library
will only be loaded the first time the <NuxtParticles> component is used in your application.
You may disable this behavior by setting the lazy option to false:
export default defineNuxtConfig({ // ... particles: { lazy: false }})Mode
The mode option allows you to choose which bundle of the tsParticles library to use. The default value is full.
slim uses the
@tsparticles/slim
package, while basic uses the
@tsparticles/basic
package. See their respective documentation for more information.
If you are not using certain advanced features of the tsParticles library, you may want to try out the slim or basic
bundles to avoid sending unnecessary JS to the client.
slim mode should work for most use-cases!export default defineNuxtConfig({ // ... particles: { mode: 'full' // 'full' | 'slim' | 'basic' | 'custom' }})Custom mode
If you'd like to fully control how the tsParticles library is loaded, you may use the custom mode. This will prevent
the nuxt-particles module from loading the tsParticles library, allowing you to load it yourself.
Lazy-loading will also be implicitly disabled.
Somewhere on the client-side of your application before the <NuxtParticles>
component is rendered, you must manually initialize the tsParticles library (such as in your app.vue):
<!-- app.vue --><template> <NuxtPage /> <!-- ... --></template><script setup lang="ts">import { tsParticles } from '@tsparticles/engine'import { loadFull } from 'tsparticles' // or whichever bundle you wish to useif (import.meta.client) { // This example will BLOCK your application from rendering until the tsParticles library is initialized // You can put this in some other place if you know that you won't be loading particles until after the first paint await loadFull(tsParticles)}</script>This also makes it possible to build a custom bundle of the tsParticles library by manually providing plugins. If bundle sizes are of the utmost importance, this is likely the best option for you.
<!-- ... --><script setup lang="ts">import { tsParticles } from '@tsparticles/engine'import { loadStarShape } from '@tsparticles/shape-star'import { loadPolygonPath } from '@tsparticles/path-polygon'await loadStarShape(tsParticles)await loadPolygonPath(tsParticles)</script>