react-script-hook

1.7.2 verified Mon Apr 27 auth: no javascript

A React hook for dynamically loading external scripts and tracking their load state. Current stable version is 1.7.2. The package is actively maintained with regular updates. It provides a simple API: call useScript with a script URL and get loading/error states. Key differentiators: automatic deduplication (multiple components loading the same script share a single request), support for onload callbacks, a checkForExisting flag for environments where the script may already be present, and conditionally loading by setting src to null. Includes TypeScript definitions and supports React 16.8.6 through 18.

Common errors

error useScript is not a function ↓

cause Incorrect import: using default import when the module was imported as a named export or vice versa.

fix

Ensure correct import: import useScript from 'react-script-hook' (default) or import { useScript } from 'react-script-hook' (named).

error Cannot read properties of undefined (reading 'src') ↓

cause Calling useScript without an object argument or with a missing src property.

fix

Pass an object with a src string: useScript({ src: 'https://example.com/script.js' })

error TypeError: Cannot read property 'appendChild' of null ↓

cause The hook runs during SSR where document.body is null.

fix

Only call useScript in client-side code. Use dynamic import or useEffect to conditionally load the hook on the client.

Warnings

gotcha Scripts are appended to <body> at the end. The hook does not remove the script tag if the component unmounts or src changes to null. ↓

fix If you need to remove the script on unmount, consider manually managing the script element or use a custom cleanup effect.

gotcha Setting src to null after it was previously set does not remove the script. The script remains in the DOM. ↓

fix Only set src to null conditionally if you intend to skip loading initially. Do not toggle src to null to remove a previously loaded script.

deprecated In version 1.7.0 and earlier, the hook returned loading, error as a tuple. This remains the same in current versions, but some users mistakenly destructure them as a single object. ↓

fix Always destructure as an array: const [loading, error] = useScript(...);

gotcha The hook relies on document.createElement and document.body.appendChild, so it will not work in server-side rendering (SSR) without a check. ↓

fix Use the checkForExisting option to avoid adding scripts in SSR, or guard with useEffect only on the client.

Install

npm install react-script-hook

yarn add react-script-hook

pnpm add react-script-hook

Imports

default
```
import useScript from 'react-script-hook'
```
Default export of the hook. Preferred and simplest usage.
named
wrong
```
const useScript = require('react-script-hook')
```
correct
```
import { useScript } from 'react-script-hook'
```
Named export also available but default is more common. Using require() works but is not recommended in ESM environments.
type-imports
```
import type { UseScriptOptions } from 'react-script-hook'
```
TypeScript users can import the options type for better DX. This is a pure type import, no runtime effect.

Quickstart

Demonstrates loading the Stripe.js script dynamically using useScript and conditionally rendering a StripeProvider only after the script loads.

import React from 'react';
import { StripeProvider } from 'react-stripe-elements';
import useScript from 'react-script-hook';
import MyCheckout from './my-checkout';

function App() {
  const [loading, error] = useScript({ src: 'https://js.stripe.com/v3/' });

  if (loading) return <h3>Loading Stripe API...</h3>;
  if (error) return <h3>Failed to load Stripe API: {error.message}</h3>;

  return (
    <StripeProvider apiKey={process.env.STRIPE_PUBLIC_KEY ?? ''}>
      <MyCheckout />
    </StripeProvider>
  );
}

export default App;