useScript

const status = useScript(src, options?);

Parameters

Parameter	Type	Description
src	string | null | undefined	The script URL. null/undefined keeps the hook idle and injects nothing — the idiomatic way to load conditionally.
options	UseScriptOptions	Optional. See below.

UseScriptOptions

Option	Type	Default	Description
removeOnUnmount	boolean	false	Remove the injected <script> on unmount, only if no other mounted useScript for the same src remains (ref-counted). Removing a script does not un-run its side effects.
shouldPreventLoad	boolean	false	When true, the hook stays idle and loads nothing regardless of src — gate a load behind consent or a feature flag.
attributes	Record<string, string>	—	Extra attributes for the created tag (id, data-*, crossorigin, async, defer, …). Applied only on creation; an adopted pre-existing tag is left untouched. Defaults to async unless async/defer is supplied here.

Returns

ScriptStatus — one of:

Value	Meaning
"idle"	Nothing is loading (src is null/undefined, shouldPreventLoad is set, or on the server).
"loading"	The <script> has been injected and is downloading/executing.
"ready"	The script fired load (or an already-loaded tag was adopted).
"error"	The script fired error (network failure, blocked, …).

Deduplication & shared status

All state lives in a module-level registry keyed by src. The first useScript(src) to mount creates one <script> (or adopts a matching tag already in the DOM) and sets a data-status attribute; every later useScript(src) shares that single tag and its status. When the script resolves, the registry flips the shared status and notifies all subscribers, so every component re-renders together.

// Two components, one <script> tag — both observe the same status.
function WidgetA() {
  const status = useScript("https://cdn.example.com/widget.js");
  return <div>A: {status}</div>;
}

function WidgetB() {
  const status = useScript("https://cdn.example.com/widget.js");
  return <div>B: {status}</div>;
}

Adopting an existing tag

If a matching <script> is already in the DOM, useScript adopts it instead of re-injecting. When it carries a data-status attribute, that status is trusted; a tag without data-status (e.g. server-rendered or added by another library) is treated as ready, because a load listener attached after the fact would never fire for a script that has already executed.

getScriptStatus(src)

Read the current shared status for a src imperatively (outside React), once some component has begun loading it:

import { getScriptStatus } from "@usefy/use-script";

if (getScriptStatus("https://cdn.example.com/sdk.js") === "ready") {
  window.SDK.init();
}