Api

useScriptTriggerInteraction()

Copy for LLMs
Last updated by Harlan Wilton in chore: lint.

Create a trigger that loads a script when any of the specified user interaction events occur. This is perfect for loading scripts only when users interact with your site, providing excellent performance optimization.

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 when any of the specified interaction events occur and the script should load, or false if the trigger is cancelled.

Nuxt Config Usage

For convenience, you can use this trigger directly in your nuxt.config without calling the composable explicitly:

export default defineNuxtConfig({
  scripts: {
    registry: {
      googleAnalytics: [{
        id: 'GA_MEASUREMENT_ID'
      }, {
        trigger: { interaction: ['scroll', 'click', 'keydown'] }
      }]
    }
  }
})

Common Event Types

Here are some commonly used interaction events:

  • Mouse events: click, mousedown, mouseup, mouseover, mouseenter, mouseleave
  • Touch events: touchstart, touchend, touchmove
  • Keyboard events: keydown, keyup, keypress
  • Scroll events: scroll, wheel
  • Focus events: focus, blur, focusin, focusout

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 { $script } = useScriptGoogleAnalytics({
  id: 'GA_MEASUREMENT_ID'
}, {
  trigger: useScriptTriggerInteraction({
    events: ['click', 'scroll', 'keydown', 'touchstart']
  })
})

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

Specific Element Targeting

Listen for events on a specific element:

<script setup lang="ts">
const headerEl = ref<HTMLElement>()

const script = useScript({
  src: 'https://example.com/header-widget.js'
}, {
  trigger: useScriptTriggerInteraction({
    events: ['click', 'mouseover'],
    target: headerEl
  })
})
</script>

<template>
  <header ref="headerEl">
    <!-- Script loads when this header is clicked or hovered -->
    <nav>...</nav>
  </header>
</template>

Progressive Feature Loading

Load features based on different interaction types:

<script setup lang="ts">
// Load search enhancement on any input interaction
const searchScript = useScript({
  src: 'https://cdn.example.com/search.js'
}, {
  trigger: useScriptTriggerInteraction({
    events: ['click', 'focus', 'keydown']
  })
})

// Load social sharing only on scroll or share button interaction
const socialScript = useScript({
  src: 'https://cdn.example.com/social-sharing.js'
}, {
  trigger: useScriptTriggerInteraction({
    events: ['scroll', 'click']
  })
})
</script>

Mobile-Optimized Loading

Use touch events for mobile-specific optimizations:

<script setup lang="ts">
// Load mobile-specific features on touch interactions
const mobileScript = useScript({
  src: 'https://cdn.example.com/mobile-features.js'
}, {
  trigger: useScriptTriggerInteraction({
    events: ['touchstart', 'touchmove', 'scroll']
  })
})
</script>

Best Practices

  • Start with common events: Use ['scroll', 'click', 'keydown'] as a good default for most use cases
  • Consider mobile users: Include touch events like touchstart for mobile optimization
  • Target specific elements: Use the target option to listen only on relevant parts of your page
  • Combine events wisely: Don't overload with too many event types - focus on meaningful interactions
  • Test performance impact: Verify that interaction-based loading improves your metrics
  • Fallback considerations: Consider what happens if users don't interact (e.g., combine with a timeout trigger)
Edit this page
Markdown For LLMs

useScriptTriggerIdleTimeout()

API documentation for the useScriptTriggerIdleTimeout function.

useScriptEventPage()

API documentation for the useScriptEventPage function.