useLazy

performance

Installation

npx usehooks-cli@latest add use-lazy

Description

A powerful React hook that enhances React.lazy with loading states, error handling, preloading capabilities, and manual control over component loading. Perfect for code splitting and performance optimization.

Parameters

Name	Type	Default	Description
importFn	() => Promise<{ default: T } \| T>	-	Function that returns a promise resolving to the component to be lazy loaded
options?	UseLazyOptions	{}	Configuration options for the lazy loading behavior

Parameter Properties

options properties:

Name	Type	Description
preload?	boolean	Whether to preload the component immediately
onLoadStart?	() => void	Callback when component starts loading
onLoadSuccess?	(component: ComponentType<any>) => void	Callback when component loads successfully
onLoadError?	(error: Error) => void	Callback when component fails to load

Return Type

UseLazyReturn<T>

Property	Type	Description
Component	T \| null	The lazy component ready to be rendered
loading	boolean	Whether the component is currently loading
error	Error \| null	Loading error if any occurred
load	() => Promise<T \| null>	Manually trigger component loading
preload	() => Promise<T \| null>	Preload the component without rendering it
reset	() => void	Reset the loading state and clear cached component

Examples

Basic Lazy Loading

Simple lazy loading with Suspense boundary

import { Suspense } from 'react';
import { useLazy } from './use-lazy';

function App() {
  const { Component } = useLazy(() => import('./HeavyComponent'));

  return (
    <Suspense fallback={<div>Loading...</div>}>
      <Component />
    </Suspense>
  );
}

With Loading States

Manual control over loading with loading states

const { Component, loading, error, load } = useLazy(
  () => import('./Dashboard'),
  {
    onLoadStart: () => console.log('Loading started'),
    onLoadSuccess: () => console.log('Component loaded'),
    onLoadError: (err) => console.error('Load failed:', err)
  }
);

if (error) return <div>Error: {error.message}</div>;
if (loading) return <div>Loading component...</div>;

return (
  <div>
    <button onClick={load}>Load Dashboard</button>
    {Component && <Component />}
  </div>
);

Preloading Components

Preload components for better performance

const { Component, preload } = useLazy(
  () => import('./ExpensiveChart'),
  { preload: true } // Preload immediately
);

// Or preload on user interaction
const handleMouseEnter = () => {
  preload(); // Preload on hover
};

return (
  <div onMouseEnter={handleMouseEnter}>
    <Suspense fallback={<ChartSkeleton />}>
      <Component />
    </Suspense>
  </div>
);

Conditional Lazy Loading

Load components based on conditions

const { Component, load, loading } = useLazy(
  () => import('./AdminPanel')
);

const [showAdmin, setShowAdmin] = useState(false);

const handleShowAdmin = async () => {
  setShowAdmin(true);
  await load(); // Ensure component is loaded
};

return (
  <div>
    <button onClick={handleShowAdmin} disabled={loading}>
      {loading ? 'Loading...' : 'Show Admin Panel'}
    </button>
    {showAdmin && Component && (
      <Suspense fallback={<div>Loading admin...</div>}>
        <Component />
      </Suspense>
    )}
  </div>
);

Dependencies

react

Notes

•Always wrap lazy components with Suspense boundary for proper loading states
•The hook caches loaded components to prevent re-loading on re-renders
•Preloading is useful for components that will likely be needed soon
•Error handling should be implemented both in the hook callbacks and with Error Boundaries
•The Component returned is compatible with React.lazy and Suspense

Implementation

"use client";

import { lazy, useState, useCallback, useRef, ComponentType } from "react";

export interface UseLazyOptions {
  /** Preload the component immediately */
  preload?: boolean;
  /** Callback when component starts loading */
  onLoadStart?: () => void;
  /** Callback when component loads successfully */
  onLoadSuccess?: (component: ComponentType<any>) => void;
  /** Callback when component fails to load */
  onLoadError?: (error: Error) => void;
}

export interface UseLazyReturn<T extends ComponentType<any>> {
  /** The lazy component */
  Component: T | null;
  /** Whether the component is currently loading */
  loading: boolean;
  /** Loading error if any */
  error: Error | null;
  /** Manually trigger component loading */
  load: () => Promise<T | null>;
  /** Preload the component without rendering */
  preload: () => Promise<T | null>;
  /** Reset the loading state */
  reset: () => void;
}

export function useLazy<T extends ComponentType<any>>(
  importFn: () => Promise<{ default: T } | T>,
  options: UseLazyOptions = {}
): UseLazyReturn<T> {
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<Error | null>(null);
  const [Component, setComponent] = useState<T | null>(null);

  const loadPromiseRef = useRef<Promise<T | null> | null>(null);
  const lazyComponentRef = useRef<T | null | React.LazyExoticComponent<T>>(
    null
  );
  const hasLoadedRef = useRef(false);

  const load = useCallback(async (): Promise<T | null> => {
    // Return existing promise if already loading
    if (loadPromiseRef.current) {
      return loadPromiseRef.current;
    }

    // Return cached component if already loaded
    if (hasLoadedRef.current && lazyComponentRef.current) {
      return lazyComponentRef.current as T;
    }

    setLoading(true);
    setError(null);
    options.onLoadStart?.();

    loadPromiseRef.current = (async () => {
      try {
        const module = await importFn();
        const component = "default" in module ? module.default : module;

        lazyComponentRef.current = component as T;
        hasLoadedRef.current = true;
        setComponent(component as T);
        setLoading(false);
        options.onLoadSuccess?.(component as T);

        return component as T;
      } catch (err) {
        const error =
          err instanceof Error ? err : new Error("Failed to load component");
        setError(error);
        setLoading(false);
        options.onLoadError?.(error);
        throw error;
      } finally {
        loadPromiseRef.current = null;
      }
    })();

    return loadPromiseRef.current;
  }, [importFn, options]);

  const preload = useCallback(async (): Promise<T | null> => {
    try {
      return await load();
    } catch (error) {
      // Preload failures are silent by default
      return null;
    }
  }, [load]);

  const reset = useCallback(() => {
    setLoading(false);
    setError(null);
    setComponent(null);
    hasLoadedRef.current = false;
    lazyComponentRef.current = null;
    loadPromiseRef.current = null;
  }, []);

  // Create lazy component that triggers loading
  const LazyComponent = useCallback(() => {
    if (!lazyComponentRef.current) {
      // Create a lazy component that will trigger our load function
      lazyComponentRef.current = lazy(async () => {
        const component = await load();
        return { default: component } as { default: T };
      });
    }
    return lazyComponentRef.current;
  }, [load]);

  // Preload if requested
  useState(() => {
    if (options.preload) {
      preload();
    }
  });

  return {
    Component: Component as T | null,
    loading,
    error,
    load,
    preload,
    reset,
  };
}

useFullscreen

CLI Docs All Hooks

useRoleGuard