This module provides a few options to customize its behavior.


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  }})
โš ๏ธ Be careful! If you disable lazy-loading, the tsParticles library will be loaded before your application using a Nuxt plugin. This will make particles render negligibly earlier at the cost of significant load-time performance. Don't disable this option unless the Total Blocking Time web vital is not of concern to your application.


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.

๐Ÿ›ˆ The 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>