useScriptTriggerInteraction()

Load a script when any configured interaction event occurs.

Listeners are attached inside onNuxtReady, so interactions that happen before Nuxt is ready do not count. Passing an empty events array leaves the promise pending.

The scope-disposal hook is also registered inside onNuxtReady. If the calling scope unmounts before Nuxt becomes ready, the callback can still attach listeners afterward; keep this trigger in a long-lived scope until that cleanup ordering is fixed.

Signature

function useScriptTriggerInteraction(options: InteractionScriptTriggerOptions): Promise<boolean>

Arguments

export interface InteractionScriptTriggerOptions {
  /**
   * The interaction events to listen for.
   */
  events: string[]
  /**
   * The element to listen for events on.
   * @default document.documentElement
   */
  target?: EventTarget | null
}

Returns

A promise that resolves to true after the first matching event. It resolves to false when target is null or the owning scope is disposed after the listeners have been attached. On the server, and when the scope disappears before onNuxtReady registers cleanup, it 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: { interaction: ['scroll', 'click', 'keydown'] }
      }
    }
  }
})

Examples

Basic Usage

Load a script when the user scrolls, clicks, or presses a key:

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

Analytics on First Interaction

Load analytics only when users interact with your site:

<script setup lang="ts">
// Load analytics on any user interaction
const { proxy, status } = useScriptGoogleAnalytics({
  id: 'GA_MEASUREMENT_ID',
  scriptOptions: {
    trigger: useScriptTriggerInteraction({
      events: ['click', 'scroll', 'keydown', 'touchstart']
    })
  }
})

// Track the first interaction
watch(status, (value) => {
  if (value === 'loaded') {
    proxy.gtag('event', 'first_interaction', {
      event_category: 'engagement'
    })
  }
})
</script>

Specific Element Targeting

The target option accepts an EventTarget that already exists when the composable runs. For Vue template refs, use useScriptTriggerElement(), which accepts a computed element ref. To preserve events that occur before hydration, bind the returned ssrAttrs to the rendered element as shown in its API reference.

Choosing Events

• Listen for interactions that indicate users will need the script soon.
• Include keyboard and touch events when the feature supports those input methods.
• Use target to limit listeners to the relevant part of the page.
• If the script must load by a deadline even without interaction, race this trigger against a timeout in a custom promise.