Skip to content

Commit c1c6d8a

Browse files
committed
doc: clarify trigger loading strategy
Fixes #489
1 parent bf491b5 commit c1c6d8a

File tree

1 file changed

+32
-2
lines changed

1 file changed

+32
-2
lines changed

docs/content/docs/1.guides/1.script-triggers.md

Lines changed: 32 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ export default defineNuxtConfig({
4545
scripts: {
4646
globals: {
4747
myScript: ['https://example.com/script.js', {
48-
// load however you like!
48+
// load after page is fully interactive (idle loading)
4949
trigger: 'onNuxtReady'
5050
}]
5151
}
@@ -57,7 +57,37 @@ export default defineNuxtConfig({
5757

5858
## Default Behavior
5959

60-
By default, scripts are loaded when Nuxt is fully hydrated. You can change this default by modifying the [defaultScriptOptions](/docs/api/nuxt-config#defaultscriptoptions).
60+
By default, scripts are loaded when Nuxt is fully hydrated using the `onNuxtReady` trigger. This provides an "idle loading" behavior where scripts load only after the page is fully interactive, minimizing impact on Core Web Vitals and user experience.
61+
62+
The `onNuxtReady` trigger ensures scripts load:
63+
- After Nuxt hydration is complete
64+
- When the browser is idle and the main thread is available
65+
- Without blocking critical page rendering or user interactions
66+
67+
This is more effective than using `defer` or `fetchpriority="low"` attributes alone, as it waits for the application to be fully ready rather than just the HTML parsing to complete.
68+
69+
You can change this default by modifying the [defaultScriptOptions](/docs/api/nuxt-config#defaultscriptoptions).
70+
71+
## Idle Loading with onNuxtReady
72+
73+
The `onNuxtReady` trigger is perfect for non-critical scripts like chat widgets, analytics, or marketing tools that should load with minimal performance impact:
74+
75+
```ts
76+
// Chat widget - loads after page is fully interactive
77+
useScript('https://widget.intercom.io/widget/abc123', {
78+
trigger: 'onNuxtReady' // default behavior
79+
})
80+
81+
// Explicitly using onNuxtReady for clarity
82+
useScriptGoogleAnalytics({
83+
id: 'GA_MEASUREMENT_ID',
84+
scriptOptions: {
85+
trigger: 'onNuxtReady'
86+
}
87+
})
88+
```
89+
90+
This approach ensures your Core Web Vitals remain optimal while still loading necessary third-party scripts.
6191

6292
## Element Event Triggers
6393

0 commit comments

Comments
 (0)