---
title: "useScript()"
description: "API documentation for the useScript function."
canonical_url: "https://scripts.nuxt.com/docs/api/use-script"
last_updated: "2026-05-03T02:50:09.408Z"
---

<callout icon="i-heroicons-play" target="_blank" to="https://stackblitz.com/github/nuxt/scripts/tree/main/examples/custom-script">

Try the live [Custom Script Example](https://stackblitz.com/github/nuxt/scripts/tree/main/examples/custom-script) on [StackBlitz](https://stackblitz.com).

</callout>

This composable is a wrapper around the Unhead [`useScript()`](https://unhead.unjs.io/usage/composables/use-script) with extra Nuxt goodies on top, for
full documentation please refer to this.

## Signature

```ts
export function useScript<T extends Record<symbol | string, any> = Record<symbol | string, any>>(input: UseScriptInput, options?: NuxtUseScriptOptions<T>): UseScriptContext<T> {}
```

## Arguments

### `UseScriptInput`

This is the script tag input. For example, you can pass a URL string or an object with the script tag attributes.

```ts
export type UseScriptInput = string | {
  src?: string
  async?: boolean
  defer?: boolean
  type?: string
  integrity?: string
  crossorigin?: string
  text?: string
  innerHTML?: string
  innerText?: string
  content?: string
  referrerPolicy?: string
  attributes?: Record<string, string>
}
```

See the [Script Input](https://unhead.unjs.io/usage/composables/use-script#argument-script-options) documentation for more information on the options.

### `NuxtUseScriptOptions`

See the [Script Options](https://unhead.unjs.io/usage/composables/use-script#argument-use-script-options) documentation for more information on the options.

- `use` - The function to resolve the script.
- `trigger` - [Triggering Script Loading](/docs/guides/script-triggers)
- `bundle` - [First-Party Mode](/docs/guides/first-party) for more information.

```ts
export type NuxtUseScriptOptions<T = any> = Omit<UseScriptOptions<T>, 'trigger'> & {
  /**
   * The trigger to load the script:
   * - `onNuxtReady` - Load the script when Nuxt is ready.
   * - `manual` - Load the script manually by calling `load()`
   * - `Promise` - Load the script when the promise resolves.
   */
  trigger?: UseScriptOptions<T>['trigger'] | 'onNuxtReady'
  /**
   * Should the script be bundled as an asset and loaded from your server. This is useful for improving the
   * performance by avoiding the extra DNS lookup and reducing the number of requests. It also
   * improves privacy by not sharing the user's IP address with third-party servers.
   * - `true` - Bundle the script as an asset.
   * - `false` - Do not bundle the script. (default)
   */
  bundle?: boolean | 'force'
  /**
   * [Experimental] Load the script in a web worker using Partytown.
   * When enabled, adds `type="text/partytown"` to the script tag.
   * Requires @nuxtjs/partytown to be installed and configured separately.
   * Note: Scripts requiring DOM access (GTM, Hotjar, chat widgets) are not compatible.
   * @see https://partytown.qwik.dev/
   */
  partytown?: boolean
  /**
   * Control proxying for this script.
   * When `false`, collection requests go directly to the third-party server.
   * When `true`, collection requests are proxied through `/_scripts/p/`.
   * Defaults based on whether the script has a `proxy` capability in the registry.
   */
  proxy?: boolean
  /**
   * Skip any schema validation for the script input. This is useful for loading the script stubs for development without
   * loading the actual script and not getting warnings.
   */
  skipValidation?: boolean
  /**
   * Specify a strategy for warming up the connection to the third-party script.
   *  - `false` - Disable preloading.
   *  - `'preload'` - Preload the script.
   *  - `'preconnect'` | `'dns-prefetch'` - Preconnect to the script origin.
   */
  warmupStrategy?: false | 'preload' | 'preconnect' | 'dns-prefetch'
}
```

## Return

See the [Understanding proxied functions](/docs/guides/key-concepts) and [$script](https://unhead.unjs.io/usage/composables/use-script#argument-use-script-options) documentation for more information on the return.

The returned object includes:

- `status` - Reactive ref with the script status: `'awaitingLoad'` | `'loading'` | `'loaded'` | `'error'`
- `load()` - Function to manually load the script
- `remove()` - Function to remove the script from the DOM
- `reload()` - Function to remove and reload the script (see below)

### `reload()`

Removes the script and reloads it, forcing re-execution. Useful for third-party scripts that scan the DOM once on load and need to re-run after SPA navigation.

```ts
const { reload } = useScript('https://example.com/dom-scanner.js')

// Reload when navigating
watch(() => route.path, () => reload())
```

<callout icon="i-heroicons-light-bulb" color="blue">

Many third-party scripts have their own SPA support (e.g., `_iub.cs.api.activateSnippets()` for iubenda). Check the script's documentation before using `reload()` - their built-in methods are usually more efficient.

</callout>