Skip to main content
Guides

Script Triggers

Copy for LLMs

Try the live Performance Example on StackBlitz to see triggers in action.

The trigger option controls when a script starts loading.

How Triggers Work

Pass a supported trigger source as trigger: the script loads when a reactive source becomes truthy, or when a promise resolves to undefined or a truthy value. A promise that resolves to false leaves the script unloaded.

const shouldLoad = ref(false)

useScript('https://example.com/script.js', {
  trigger: shouldLoad
})

// Later: trigger loading
shouldLoad.value = true

This works with refs, computed refs, getter functions, and promises:

// Ref
trigger: shouldLoad

// Computed
trigger: computed(() => !!route.query.affiliateId)

// Getter function
trigger: () => shouldLoad.value

// Promise
trigger: new Promise(resolve => setTimeout(resolve, 3000))

Default: onNuxtReady

By default, scripts use the onNuxtReady trigger. Nuxt waits for hydration, then schedules the load with requestIdleCallback or a short timer fallback.

// The default, written explicitly
useScript('https://widget.intercom.io/widget/abc123', {
  trigger: 'onNuxtReady'
})

// Registry composables inherit onNuxtReady by default
useScriptGoogleAnalytics({
  id: 'GA_MEASUREMENT_ID',
  // trigger: 'onNuxtReady' is implied
})

Registry composables inherit this default unless an integration defines an earlier trigger. A registry entry in nuxt.config still needs an explicit trigger to create a global instance; an entry without one only enables its types, bundling, proxy routes, and other infrastructure.

partytown: true is an exception. The current Partytown path inserts the script during SSR and reports it as loaded, so it does not wait for trigger. A registry entry still needs a truthy trigger to generate the global instance, but the trigger value does not control when that Partytown script runs.

You can change this default by modifying the defaultScriptOptions.

Specialized Triggers

Idle Timeout

useScriptTriggerIdleTimeout() starts its timer after Nuxt is ready:

useScript('https://example.com/analytics.js', {
  trigger: useScriptTriggerIdleTimeout({ timeout: 5000 })
})

User Interaction

useScriptTriggerInteraction() resolves on the first configured interaction:

useScript('https://example.com/chat-widget.js', {
  trigger: useScriptTriggerInteraction({
    events: ['scroll', 'click', 'keydown']
  })
})

Element Event Triggers

useScriptTriggerElement() watches one element for visibility or events:

const buttonEl = ref<HTMLElement>()

useScript('https://example.com/feature.js', {
  trigger: useScriptTriggerElement({
    trigger: 'visible', // or 'mouseover', 'click', etc.
    el: buttonEl,
  })
})

Basic Triggers

Manual Control

Use the manual trigger when your code should call load() directly:

const { load } = useScript('https://example.com/script.js', {
  trigger: 'manual'
})

// Load when you decide
await load()
Edit this page
Markdown For LLMs

Registry Scripts

Configure, reuse, and extend typed integrations from the Nuxt Scripts registry.

Warmup Strategy

Customize the preload or preconnect strategy used for your scripts.