useScriptTriggerIdleTimeout()
Load a noncritical script after Nuxt is ready and the configured idle timeout has elapsed.
The trigger uses a timer after onNuxtReady; it does not wait for the browser's requestIdleCallback.
Signature
function useScriptTriggerIdleTimeout(options: IdleTimeoutScriptTriggerOptions): UseScriptTriggerArguments
export interface IdleTimeoutScriptTriggerOptions {
/**
* The timeout in milliseconds to wait before loading the script.
*/
timeout: number
}Returns
An Unhead trigger function for scriptOptions.trigger. It starts the timer after
Nuxt is ready and loads the script when the timeout completes. Disposing the
consumer scope cancels the pending timer, including when disposal happens before
Nuxt becomes ready. The trigger does not install a timer during SSR.
Nuxt Config Usage
Registry entries and global scripts accept the trigger directly in nuxt.config:
export default defineNuxtConfig({
scripts: {
registry: {
googleAnalytics: {
id: 'GA_MEASUREMENT_ID',
trigger: { idleTimeout: 3000 } // Load 3 seconds after Nuxt ready
}
}
}
})export default defineNuxtConfig({
scripts: {
globals: {
chatWidget: ['https://widget.example.com/chat.js', {
trigger: { idleTimeout: 5000 } // Load 5 seconds after Nuxt ready
}]
}
}
})Examples
Basic Usage
Load a script 5 seconds after Nuxt is ready:
const script = useScript({
src: 'https://example.com/analytics.js',
}, {
trigger: useScriptTriggerIdleTimeout({ timeout: 5000 })
})Delayed Analytics Loading
Delay analytics that does not need to load immediately:
<script setup lang="ts">
// Load Google Analytics after a 3-second delay
const { status } = useScriptGoogleAnalytics({
id: 'GA_MEASUREMENT_ID',
scriptOptions: {
trigger: useScriptTriggerIdleTimeout({ timeout: 3000 })
}
})
// The registry sends its initial page view when the delayed tag initializes.
watch(status, (value) => {
if (value === 'loaded') {
console.log('Google Analytics loaded')
}
})
</script>Delay Nonessential UI
Give critical resources a head start before loading widgets and search helpers:
<script setup lang="ts">
// Load chat widget after 10 seconds
const chatScript = useScript({
src: 'https://widget.intercom.io/widget/abc123'
}, {
trigger: useScriptTriggerIdleTimeout({ timeout: 10000 })
})
// Load search enhancement after 5 seconds
const searchScript = useScript({
src: 'https://cdn.example.com/search-enhancement.js'
}, {
trigger: useScriptTriggerIdleTimeout({ timeout: 5000 })
})
</script>Choosing a Timeout
- Pick a delay for the feature, not a site-wide default.
- Shorten it when users are likely to need the feature early.
- Measure Core Web Vitals to confirm that the delay helps.
- A script accepts one trigger. Use a custom promise to race a timeout against an interaction.