useScriptTag

Dynamically load and unload an external script tag. The script is appended to document.head on mount and removed on unmount. Supports promise-based control, deduplication of identical scripts, and optional manual lifecycle management.

Demo

useScriptTag

Not loaded

Dynamically load and unload an external script tag.

srccdn.jsdelivr.net/npm/dayjs@1/dayjs.min.js

LoadUnload

Usage

Hook

import { useScriptTag } from "@usels/web";

function Component() {
  const { isLoaded$ } = useScriptTag("https://cdn.example.com/lib.js", (el) => {
    console.log("Script loaded", el);
  });

  return <div>{isLoaded$.get() ? "Script loaded" : "Loading..."}</div>;
}

Scope

import { createScriptTag } from "@usels/web";

function Component() {
  "use scope"
  const { isLoaded$ } = createScriptTag("https://cdn.example.com/lib.js", (el) => {
    console.log("Script loaded", el);
  });

  return <div>{isLoaded$.get() ? "Script loaded" : "Loading..."}</div>;
}

Manual control

Set manual: true to take full control of when the script loads and unloads.

Hook

import { useScriptTag } from "@usels/web";

function Component() {
  const { load, unload, isLoaded$ } = useScriptTag(
    "https://cdn.example.com/lib.js",
    undefined,
    { manual: true }
  );

  return (
    <div>
      <button onClick={() => load()}>Load</button>
      <button onClick={() => unload()}>Unload</button>
      <p>Status: {isLoaded$.get() ? "loaded" : "not loaded"}</p>
    </div>
  );
}

Scope

import { createScriptTag } from "@usels/web";

function Component() {
  "use scope"
  const { load, unload, isLoaded$ } = createScriptTag(
    "https://cdn.example.com/lib.js",
    undefined,
    { manual: true }
  );

  return (
    <div>
      <button onClick={() => load()}>Load</button>
      <button onClick={() => unload()}>Unload</button>
      <p>Status: {isLoaded$.get() ? "loaded" : "not loaded"}</p>
    </div>
  );
}

Wait for script load

load() accepts a waitForScriptLoad parameter (default true). When true, the returned promise resolves only after the script’s load event fires. Set to false to resolve immediately after the element is appended.

const { load } = useScriptTag("https://cdn.example.com/lib.js", undefined, { manual: true });

// Resolves after the `load` event fires
await load(true);

// Resolves immediately after appending to DOM
await load(false);

With options

import { useScriptTag } from "@usels/web";

useScriptTag("https://cdn.example.com/lib.js", undefined, {
  async: true, // default: true
  defer: false,
  type: "text/javascript", // default: "text/javascript"
  crossOrigin: "anonymous",
  referrerPolicy: "no-referrer",
  nonce: "abc123",
  attrs: { "data-id": "my-lib" },
});

Type

Parameters

Parameter	Type	Description
src	MaybeObservable<string>	- Script src (MaybeObservable<string> — read at load time).
onLoaded	(el: HTMLScriptElement) => void (optional)	- Optional callback invoked once the script’s load event fires.
options	UseScriptTagOptions (optional)	- Mount-time-only options (immediate, manual, attrs, etc.).

UseScriptTagOptions

Option	Type	Default	Description
immediate	boolean	true	Load the script immediately on mount
async	boolean	true	Set the script element’s async attribute
type	string	"text/javascript"	Script MIME type
manual	boolean	false	Manual control — if true, load/unload are not called automatically on mount/unmount
crossOrigin	"anonymous" | "use-credentials"	-	-
referrerPolicy	ReferrerPolicy	-	-
noModule	boolean	-	-
defer	boolean	-	-
attrs	Record<string, string>	-	Additional attributes to set on the script element
nonce	string	-	-
document	Document	-	Custom document instance (useful for iframes or testing)

Returns

UseScriptTagReturn

Name	Type	Description
scriptTag$	ReadonlyObservable<HTMLScriptElement | null>	-
isLoaded$	ReadonlyObservable<boolean>	True once the script’s load event has fired (or a pre-loaded element was found). Resets to false on unload().
load	(waitForScriptLoad?: boolean | undefined) => Promise<boolean | HTMLScriptElement>	-
unload	() => void	-

Source

View on GitHub