React useScript Hook

Ever tried to load external scripts in React and ended up with document.createElement chaos, duplicate script loading nightmares, or broken loading state management? You know the drill—manually creating script tags, forgetting to check if scripts already exist, dealing with loading state tracking, handling cleanup on unmount. This free open source React useScript custom hook handles all that dynamic script loading complexity so you can focus on building features instead of debugging third-party integration edge cases in your React applications.

useScript showcase

Smart script loading with automatic caching and status tracking:

"use client";import { toast } from "sonner";import { Button } from "@/components/ui/button";import { Badge } from "@/components/ui/badge";import { Label } from "@/components/ui/label";import { useScript } from '@/components/ui/shadcn-io/use-script';export default function UseScriptDemo() {  const status = useScript('https://cdn.jsdelivr.net/npm/[email protected]/dist/confetti.browser.min.js', {    removeOnUnmount: false,    id: 'confetti-script',  });  const triggerConfetti = () => {    if (status === 'ready' && typeof window !== 'undefined' && 'confetti' in window) {      // @ts-ignore - confetti is loaded dynamically      window.confetti({        particleCount: 100,        spread: 70,        origin: { y: 0.6 }      });      toast.success("🎉 Confetti triggered!", {        description: "Canvas-confetti library loaded and executed",      });    }  };  const getStatusVariant = (status: string): "default" | "secondary" | "destructive" => {    switch (status) {      case 'ready': return 'default';      case 'error': return 'destructive';      default: return 'secondary';    }  };  const getStatusIcon = (status: string) => {    switch (status) {      case 'loading': return '⏳';      case 'ready': return '✅';      case 'error': return '❌';      default: return '⚪';    }  };  return (    <div className="p-6 max-w-sm mx-auto space-y-4">      {/* Header */}      <div className="text-center space-y-1">        <h3 className="text-lg font-semibold">Script Loader Demo</h3>        <p className="text-sm text-muted-foreground">Dynamic canvas-confetti loading</p>      </div>            {/* Status Display */}      <div className="space-y-2">        <Label className="text-sm font-medium">Loading Status</Label>        <div className="bg-muted rounded p-2 min-h-[40px] flex items-center justify-center">          <div className="flex items-center gap-2">            <span className="text-lg">{getStatusIcon(status)}</span>            <Badge variant={getStatusVariant(status)} className="text-sm px-3 py-1 font-mono">              {status}            </Badge>          </div>        </div>      </div>      {/* Action Button */}      <div className="space-y-2">        <Label className="text-sm font-medium">Test Script</Label>        <div className="min-h-[40px] flex items-center">          <Button            onClick={triggerConfetti}            disabled={status !== 'ready'}            variant={status === 'ready' ? 'default' : 'outline'}            className="w-full h-10"          >            {status === 'ready' ? '🎉 Trigger Confetti!' : 'Loading script...'}          </Button>        </div>      </div>      {/* Status Messages */}      <div className="text-center min-h-[32px] flex items-center justify-center">        {status === 'ready' && (          <div className="text-xs text-green-600">            Script loaded! Click button to test confetti          </div>        )}                {status === 'error' && (          <div className="text-xs text-red-600">            Failed to load script. Check your connection.          </div>        )}        {status === 'loading' && (          <div className="text-xs text-muted-foreground">            Loading canvas-confetti from CDN...          </div>        )}        {status === 'idle' && (          <div className="text-xs text-muted-foreground">            Script loader ready          </div>        )}      </div>    </div>  );}

import * as React from "react"import { Slot } from "@radix-ui/react-slot"import { cva, type VariantProps } from "class-variance-authority"import { cn } from "@/lib/utils"const buttonVariants = cva(  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive",  {    variants: {      variant: {        default:          "bg-primary text-primary-foreground shadow-xs hover:bg-primary/90",        destructive:          "bg-destructive text-white shadow-xs hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60",        outline:          "border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50",        secondary:          "bg-secondary text-secondary-foreground shadow-xs hover:bg-secondary/80",        ghost:          "hover:bg-accent hover:text-accent-foreground dark:hover:bg-accent/50",        link: "text-primary underline-offset-4 hover:underline",      },      size: {        default: "h-9 px-4 py-2 has-[>svg]:px-3",        sm: "h-8 rounded-md gap-1.5 px-3 has-[>svg]:px-2.5",        lg: "h-10 rounded-md px-6 has-[>svg]:px-4",        icon: "size-9",      },    },    defaultVariants: {      variant: "default",      size: "default",    },  })function Button({  className,  variant,  size,  asChild = false,  ...props}: React.ComponentProps<"button"> &  VariantProps<typeof buttonVariants> & {    asChild?: boolean  }) {  const Comp = asChild ? Slot : "button"  return (    <Comp      data-slot="button"      className={cn(buttonVariants({ variant, size, className }))}      {...props}    />  )}export { Button, buttonVariants }

This free open source React hook simplifies external script integration with TypeScript support for modern JavaScript applications. Whether you're loading analytics SDKs, payment gateways, or social widgets in your Next.js projects, this React hook keeps your script loading reliable and performant.

Installation

npx shadcn@latest add https://www.shadcn.io/registry/use-script.json

npx shadcn@latest add https://www.shadcn.io/registry/use-script.json

pnpm dlx shadcn@latest add https://www.shadcn.io/registry/use-script.json

bunx shadcn@latest add https://www.shadcn.io/registry/use-script.json

Why most script loading implementations suck

Look, you could keep manually creating script elements and managing loading states. But then you hit the script loading complexity—duplicate script tags cluttering the DOM, missed loading events, race conditions with multiple components, broken cleanup causing memory leaks in React applications.

Most developers manually create script tags with document.createElement() without proper deduplication, leading to the same script being loaded multiple times in TypeScript components. Or they forget to track loading states properly, causing race conditions when multiple components need the same script. Some skip cleanup entirely and wonder why their third-party scripts accumulate memory leaks when components unmount in Next.js projects.

This React hook uses optimized script management under the hood, with automatic caching to prevent duplicate loads and shared status across components in JavaScript applications. The browser handles all the script loading, plus you get comprehensive error handling and cleanup options in one call.

Plus it handles all the edge cases—SSR compatibility with proper hydration, script deduplication across components, automatic status sharing, proper event listener cleanup in React development. No more scattered script tags or broken third-party integrations.

This free open source React hook manages script state while you focus on building features. Whether you're creating React applications, Next.js dashboards, or TypeScript components, reliable script loading keeps your JavaScript development smooth.

Features

• Dynamic script loading with automatic status tracking and comprehensive error handling in React applications
• Script caching preventing duplicate loads and sharing status across components in TypeScript components
• Loading state management providing idle, loading, ready, and error states in Next.js projects
• Cleanup options with configurable script removal on component unmount in JavaScript development
• SSR compatibility with proper server-side rendering support and hydration safety for React frameworks
• TypeScript support with comprehensive type definitions and status enums in modern applications
• Free open source designed for modern React development workflows

When you'll actually use this

Real talk—this isn't for every external resource in React applications. Static assets in your build process handle most script needs perfectly. But when you need dynamic third-party integration with conditional loading or runtime script management, this React hook delivers in Next.js projects.

Perfect for:

• Analytics and tracking - Load Google Analytics, Mixpanel, or custom tracking conditionally built with TypeScript
• Payment processing - Load Stripe, PayPal, or payment gateway SDKs when needed using React patterns
• Social integrations - Load Twitter embeds, Facebook widgets, or social sharing on demand in JavaScript applications
• CDN libraries - Load utility libraries, polyfills, or fallback scripts dynamically in React components
• A/B testing tools - Load experiment scripts based on user segments or conditions in Next.js applications
• Chat widgets - Load customer support, Intercom, or help desk scripts conditionally using TypeScript safety

API Reference

useScript

useScript(
  src: string | null,
  options?: UseScriptOptions
): UseScriptStatus

UseScriptOptions

UseScriptStatus

Common gotchas

Script caching is global: All components using the same URL share the same loading status in React applications. The first component to load a script determines the state for all others. This prevents duplicate requests but means error states are also shared.

Third-party scripts can affect performance: The React hook itself is lightweight, but the scripts you load can significantly impact your app in TypeScript components. Use conditional loading to delay non-essential scripts and monitor third-party performance.

Security is your responsibility: Dynamically loaded scripts have full page access just like static scripts in Next.js projects. Only load from trusted domains and implement proper Content Security Policy headers.

SSR returns 'idle' initially: Scripts only load after client hydration, so handle the case where global objects from scripts aren't available yet during SSR in JavaScript applications.

Script load timing varies: External scripts may load at different speeds based on network conditions in React frameworks. Always handle loading states gracefully to avoid broken functionality.

Global namespace pollution: Third-party scripts may modify global objects in TypeScript projects. Consider defensive programming practices to avoid conflicts with your application code.

Related hooks you will also like

Questions you might have