Api
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): Promise<boolean>
Arguments
export interface IdleTimeoutScriptTriggerOptions {
/**
* The timeout in milliseconds to wait before loading the script.
*/
timeout: number
}
Returns
A promise that resolves to true when the timeout completes. If the owning Vue scope is disposed after the timer starts, it stops the timer and resolves to false. On the server, and if the scope disappears before onNuxtReady runs, the promise remains pending.
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
}
}
}
})
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.