Unhead

Usage

import { useScript } from 'unhead'

const { onLoaded } = useScript('https://example.com/script.js')

onLoaded(() => {
  // Script loaded successfully
})

Defaults

A singleton pattern is implemented scripts with the same src or key are only loaded once globally. This helps prevent duplicate script loading and ensures consistent initialization.

  • Scripts load after hydration by default
  • defer enabled for proper execution order
  • fetchpriority="low" to prioritize critical resources
  • crossorigin="anonymous" prevents cookie access
  • referrerpolicy="no-referrer" blocks referrer headers

Script Input

Pass either a URL string or options object:

// URL only
useScript('https://example.com/script.js')

// Full options - accepts any <script> attribute
useScript({
  src: 'https://example.com/script.js',
  crossorigin: false // disable crossorigin='anonymous'
})

Loading Options

Control when and how scripts load:

useScript(input, {
  // When to load the script
  trigger: 'client' | 'server' | Promise | ((load) => void),

  // Resource hint strategy
  warmupStrategy: 'preload' | 'prefetch' | 'preconnect' | 'dns-prefetch',

  // Access the script's API
  use: () => window.externalAPI
})

Script Lifecycle

The script goes through these states:

  • awaitingLoad - Initial state
  • loading - Script is loading
  • loaded - Script loaded successfully
  • error - Script failed to load
  • removed - Script was removed

Monitor these with:

script.onLoaded((api) => {
  // Script loaded
})

script.onError(() => {
  // Script failed
})

Resource Hints

The warmupStrategy option automatically adds resource hints to optimize loading:

useScript(input, {
  // Preload - highest priority, load ASAP
  warmupStrategy: 'preload',

  // Prefetch - load when browser is idle
  warmupStrategy: 'prefetch',

  // Preconnect - setup connection early
  warmupStrategy: 'preconnect',

  // DNS Prefetch - resolve DNS early
  warmupStrategy: 'dns-prefetch'
})

API Proxying

If you need to access the script's API before it loads, use the use option with proxy support.

const script = useScript({
  src: 'https://maps.googleapis.com/maps/api/js'
}, {
  use: () => window.google.maps
})

// Works before script loads!
script.proxy.Map()

The proxy records all calls and replays them once loaded.

Did this page help you?

useSeoMeta()

The simplest way to add meta tags to your site.

Upgrade Guide

Learn about how to migrate to Unhead v2 from v1