use-script-tag

Inject a <script> tag and track its loading state.


Package	`@vizejs/composable/use-script-tag`
Own the source	`vize lib pull composable:use-script-tag`
Runtime exports	`useScriptTag`
Gzip budget	2816 B

Usage

import { useScriptTag } from "@vizejs/composable/use-script-tag";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useScriptTag`	dom	experimental	deterministic-fallback	caller-managed	caller, reactive-scope	web, desktop	`window`	`tryOnScopeDispose`

API

`useScriptTag`

Inject a <script> tag and track its loading state. An existing tag with the same src is reused instead of duplicated: if it was created by another useScriptTag call its state is shared through a data-vize-script-status attribute; a tag without that attribute (for example emitted in server-rendered HTML) is assumed to have executed. Changing the reactive src unloads the previous script and, with immediate, loads the new one. Server rendering: no document exists, so nothing is injected, status stays "idle", and load resolves "unsupported". Emit server-side script tags through the application's head manager. Scripts created by this composable are removed when the owning scope stops (configurable); already-executed code cannot be unloaded.

function useScriptTag( src: MaybeRefOrGetter<string>, options: UseScriptTagOptions = {}, ): ScriptTagControls

const { status } = useScriptTag("https://example.com/widget.js", {
  onLoaded: () => window.Widget.init(),
});

Types

`ScriptTagElement`

<script> subset used by useScriptTag.

Member	Type	Description
`getAttribute`	`(name: string) => string \| null`	Read an attribute.
`setAttribute`	`(name: string, value: string) => void`	Write an attribute.

`ScriptTagHost`

Document capability used by useScriptTag.

Member	Type	Description
`findScript`	`(src: string) => ScriptTagElement \| undefined`	Find an existing `<script>` whose `src` attribute equals `src`.
`createScript`	`() => ScriptTagElement`	Create a detached `<script>`.
`append`	`(element: ScriptTagElement) => void`	Attach a script to `<head>`, starting its download.
`remove`	`(element: ScriptTagElement) => void`	Detach a script.

`UseScriptTagOptions`

Options for useScriptTag.

Member	Type	Description
`onLoaded`?	`(element: ScriptTagElement) => void`	Called once the script has loaded.
`immediate`?	`boolean`	Load when created and whenever `src` changes.
`async`?	`boolean`	Set the `async` attribute.
`defer`?	`boolean`	Set the `defer` attribute.
`type`?	`string`	Script `type` (for example `"module"`).
`crossOrigin`?	`"anonymous" \| "use-credentials"`	CORS mode (`crossorigin` attribute).
`referrerPolicy`?	`ReferrerPolicy`	Referrer policy.
`noModule`?	`boolean`	Set the `nomodule` attribute.
`nonce`?	`string`	CSP nonce.
`integrity`?	`string`	Subresource integrity hash.
`attributes`?	`Readonly<Record<string, string>>`	Additional attributes.
`removeOnDispose`?	`boolean`	Remove a script created by this composable when the owning scope stops.
`host`?	`MaybeRefOrGetter<ScriptTagHost \| null \| undefined>`	Document capability for alternate runtimes and tests.

`ScriptTagControls`

Reactive state and actions returned by useScriptTag.

Member	Type	Description
`status`	`Readonly<Ref<ScriptTagStatus>>`	Loading state.
`element`	`Readonly<ShallowRef<ScriptTagElement \| undefined>>`	Script element in use, if any.
`load`	`() => Promise<ScriptTagResult>`	Load the script (or reuse an existing tag with the same `src`). Concurrent calls share one load; `unload` and scope disposal resolve a pending load as `"cancelled"`.
`unload`	`() => void`	Remove a script created by this composable and reset the state.