React Custom Hooks Library

1// useLocalStorage - Sync state with localStorage
2import { useState, useEffect, useCallback } from 'react';
3
4function useLocalStorage<T>(
5  key: string,
6  initialValue: T,
7  options?: {
8    serializer?: (value: T) => string;
9    deserializer?: (value: string) => T;
10  }
11): [T, (value: T | ((val: T) => T)) => void, () => void] {
12  const { 
13    serializer = JSON.stringify, 
14    deserializer = JSON.parse 
15  } = options || {};
16
17  // Get initial value from localStorage or use provided initial value
18  const [storedValue, setStoredValue] = useState<T>(() => {
19    try {
20      if (typeof window === 'undefined') {
21        return initialValue;
22      }
23      
24      const item = window.localStorage.getItem(key);
25      return item ? deserializer(item) : initialValue;
26    } catch (error) {
27      console.error(`Error loading localStorage key "${key}":`, error);
28      return initialValue;
29    }
30  });
31
32  // Update localStorage when state changes
33  const setValue = useCallback((value: T | ((val: T) => T)) => {
34    try {
35      const valueToStore = value instanceof Function ? value(storedValue) : value;
36      setStoredValue(valueToStore);
37      
38      if (typeof window !== 'undefined') {
39        window.localStorage.setItem(key, serializer(valueToStore));
40        
41        // Dispatch storage event for cross-tab synchronization
42        window.dispatchEvent(new StorageEvent('storage', {
43          key,
44          newValue: serializer(valueToStore),
45          url: window.location.href,
46          storageArea: window.localStorage
47        }));
48      }
49    } catch (error) {
50      console.error(`Error saving to localStorage key "${key}":`, error);
51    }
52  }, [key, serializer, storedValue]);
53
54  // Remove value from localStorage
55  const removeValue = useCallback(() => {
56    try {
57      setStoredValue(initialValue);
58      if (typeof window !== 'undefined') {
59        window.localStorage.removeItem(key);
60      }
61    } catch (error) {
62      console.error(`Error removing localStorage key "${key}":`, error);
63    }
64  }, [key, initialValue]);
65
66  // Listen for changes in other tabs
67  useEffect(() => {
68    const handleStorageChange = (e: StorageEvent) => {
69      if (e.key === key && e.newValue) {
70        try {
71          setStoredValue(deserializer(e.newValue));
72        } catch (error) {
73          console.error(`Error parsing localStorage update for key "${key}":`, error);
74        }
75      }
76    };
77
78    window.addEventListener('storage', handleStorageChange);
79    return () => window.removeEventListener('storage', handleStorageChange);
80  }, [key, deserializer]);
81
82  return [storedValue, setValue, removeValue];
83}
84
85// Usage example
86function Settings() {
87  const [theme, setTheme, resetTheme] = useLocalStorage('theme', 'light');
88  const [preferences, setPreferences] = useLocalStorage('userPrefs', {
89    notifications: true,
90    autoSave: false,
91    language: 'en'
92  });
93
94  return (
95    <div>
96      <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
97        Toggle Theme: {theme}
98      </button>
99      
100      <button onClick={() => setPreferences(prev => ({
101        ...prev,
102        notifications: !prev.notifications
103      }))}>
104        Notifications: {preferences.notifications ? 'On' : 'Off'}
105      </button>
106      
107      <button onClick={resetTheme}>Reset Theme</button>
108    </div>
109  );
110}

1// useDebounce - Delay value updates
2import { useState, useEffect } from 'react';
3
4function useDebounce<T>(value: T, delay: number): T {
5  const [debouncedValue, setDebouncedValue] = useState<T>(value);
6
7  useEffect(() => {
8    const handler = setTimeout(() => {
9      setDebouncedValue(value);
10    }, delay);
11
12    return () => {
13      clearTimeout(handler);
14    };
15  }, [value, delay]);
16
17  return debouncedValue;
18}
19
20// Advanced version with callback
21function useDebouncedCallback<T extends (...args: any[]) => any>(
22  callback: T,
23  delay: number,
24  deps: React.DependencyList = []
25): T {
26  const [timer, setTimer] = useState<NodeJS.Timeout>();
27
28  useEffect(() => {
29    return () => {
30      if (timer) clearTimeout(timer);
31    };
32  }, [timer]);
33
34  const debouncedCallback = useCallback((...args: Parameters<T>) => {
35    if (timer) clearTimeout(timer);
36    
37    const newTimer = setTimeout(() => {
38      callback(...args);
39    }, delay);
40    
41    setTimer(newTimer);
42  }, [callback, delay, ...deps]) as T;
43
44  return debouncedCallback;
45}
46
47// Usage example
48function SearchComponent() {
49  const [searchTerm, setSearchTerm] = useState('');
50  const debouncedSearchTerm = useDebounce(searchTerm, 500);
51  
52  const [results, setResults] = useState([]);
53  const [isSearching, setIsSearching] = useState(false);
54
55  // Search when debounced value changes
56  useEffect(() => {
57    if (debouncedSearchTerm) {
58      setIsSearching(true);
59      searchAPI(debouncedSearchTerm).then(results => {
60        setIsSearching(false);
61        setResults(results);
62      });
63    } else {
64      setResults([]);
65    }
66  }, [debouncedSearchTerm]);
67
68  // Using debounced callback
69  const debouncedSearch = useDebouncedCallback(
70    (term: string) => {
71      console.log('Searching for:', term);
72      // Perform search
73    },
74    300
75  );
76
77  return (
78    <div>
79      <input
80        placeholder="Search..."
81        value={searchTerm}
82        onChange={(e) => {
83          setSearchTerm(e.target.value);
84          debouncedSearch(e.target.value);
85        }}
86      />
87      {isSearching && <div>Searching...</div>}
88      {results.map(result => (
89        <div key={result.id}>{result.name}</div>
90      ))}
91    </div>
92  );
93}

1// useToggle - Enhanced boolean state management
2import { useState, useCallback } from 'react';
3
4function useToggle(
5  initialValue: boolean = false
6): [boolean, {
7  toggle: () => void;
8  on: () => void;
9  off: () => void;
10  set: (value: boolean) => void;
11}] {
12  const [value, setValue] = useState(initialValue);
13
14  const toggle = useCallback(() => setValue(v => !v), []);
15  const on = useCallback(() => setValue(true), []);
16  const off = useCallback(() => setValue(false), []);
17  const set = useCallback((newValue: boolean) => setValue(newValue), []);
18
19  return [value, { toggle, on, off, set }];
20}
21
22// Usage example
23function Modal() {
24  const [isOpen, { toggle, on: open, off: close }] = useToggle(false);
25  const [isLoading, loadingControls] = useToggle(false);
26
27  const handleSubmit = async () => {
28    loadingControls.on();
29    try {
30      await submitData();
31      close();
32    } finally {
33      loadingControls.off();
34    }
35  };
36
37  return (
38    <>
39      <button onClick={open}>Open Modal</button>
40      
41      {isOpen && (
42        <div className="modal">
43          <div className="modal-content">
44            <h2>Modal Title</h2>
45            <button onClick={close}>×</button>
46            
47            <button 
48              onClick={handleSubmit}
49              disabled={isLoading}
50            >
51              {isLoading ? 'Submitting...' : 'Submit'}
52            </button>
53          </div>
54        </div>
55      )}
56    </>
57  );
58}

1// usePrevious - Remember previous values
2import { useRef, useEffect } from 'react';
3
4function usePrevious<T>(value: T): T | undefined {
5  const ref = useRef<T>();
6  
7  useEffect(() => {
8    ref.current = value;
9  }, [value]);
10  
11  return ref.current;
12}
13
14// Advanced version with comparison
15function usePreviousDistinct<T>(
16  value: T, 
17  isEqual: (a: T | undefined, b: T) => boolean = (a, b) => a === b
18): T | undefined {
19  const ref = useRef<T>();
20  const prevValue = ref.current;
21  
22  if (!isEqual(prevValue, value)) {
23    ref.current = value;
24  }
25  
26  return prevValue;
27}
28
29// Usage example
30function Counter() {
31  const [count, setCount] = useState(0);
32  const prevCount = usePrevious(count);
33  
34  const [user, setUser] = useState({ name: 'John', age: 30 });
35  const prevUser = usePreviousDistinct(user, (a, b) => 
36    a?.name === b.name && a?.age === b.age
37  );
38
39  return (
40    <div>
41      <h3>
42        Now: {count}, before: {prevCount ?? 'N/A'}
43      </h3>
44      <button onClick={() => setCount(count + 1)}>
45        Increment
46      </button>
47      
48      {prevUser && user.name !== prevUser.name && (
49        <p>Name changed from {prevUser.name} to {user.name}</p>
50      )}
51    </div>
52  );
53}

1// useClickOutside - Handle outside clicks
2import { useEffect, useRef, RefObject } from 'react';
3
4function useClickOutside<T extends HTMLElement = HTMLElement>(
5  handler: (event: MouseEvent | TouchEvent) => void,
6  mouseEvent: 'mousedown' | 'mouseup' = 'mousedown'
7): RefObject<T> {
8  const ref = useRef<T>(null);
9
10  useEffect(() => {
11    const listener = (event: MouseEvent | TouchEvent) => {
12      const element = ref.current;
13      if (!element || element.contains(event.target as Node)) {
14        return;
15      }
16      handler(event);
17    };
18
19    document.addEventListener(mouseEvent, listener);
20    document.addEventListener('touchstart', listener);
21
22    return () => {
23      document.removeEventListener(mouseEvent, listener);
24      document.removeEventListener('touchstart', listener);
25    };
26  }, [handler, mouseEvent]);
27
28  return ref;
29}
30
31// Alternative version with multiple refs
32function useClickOutsideMultiple(
33  refs: RefObject<HTMLElement>[],
34  handler: (event: MouseEvent | TouchEvent) => void
35) {
36  useEffect(() => {
37    const listener = (event: MouseEvent | TouchEvent) => {
38      const isOutside = refs.every(ref => {
39        const element = ref.current;
40        return !element || !element.contains(event.target as Node);
41      });
42
43      if (isOutside) {
44        handler(event);
45      }
46    };
47
48    document.addEventListener('mousedown', listener);
49    document.addEventListener('touchstart', listener);
50
51    return () => {
52      document.removeEventListener('mousedown', listener);
53      document.removeEventListener('touchstart', listener);
54    };
55  }, [refs, handler]);
56}
57
58// Usage example
59function Dropdown() {
60  const [isOpen, setIsOpen] = useState(false);
61  const dropdownRef = useClickOutside<HTMLDivElement>(() => {
62    setIsOpen(false);
63  });
64
65  return (
66    <div ref={dropdownRef} className="dropdown">
67      <button onClick={() => setIsOpen(!isOpen)}>
68        Toggle Dropdown
69      </button>
70      
71      {isOpen && (
72        <div className="dropdown-content">
73          <a href="#">Option 1</a>
74          <a href="#">Option 2</a>
75          <a href="#">Option 3</a>
76        </div>
77      )}
78    </div>
79  );
80}

1// useIntersectionObserver - Track element visibility
2import { useState, useEffect, useRef, RefObject } from 'react';
3
4interface UseIntersectionObserverOptions extends IntersectionObserverInit {
5  freezeOnceVisible?: boolean;
6}
7
8function useIntersectionObserver<T extends HTMLElement = HTMLElement>(
9  options?: UseIntersectionObserverOptions
10): [RefObject<T>, IntersectionObserverEntry | undefined] {
11  const { threshold = 0, root = null, rootMargin = '0px', freezeOnceVisible = false } = options || {};
12  const [entry, setEntry] = useState<IntersectionObserverEntry>();
13  const [frozen, setFrozen] = useState(false);
14  const ref = useRef<T>(null);
15
16  useEffect(() => {
17    const node = ref.current;
18    if (!node || frozen) return;
19
20    const observer = new IntersectionObserver(
21      ([entry]) => {
22        setEntry(entry);
23        if (freezeOnceVisible && entry.isIntersecting) {
24          setFrozen(true);
25        }
26      },
27      { threshold, root, rootMargin }
28    );
29
30    observer.observe(node);
31    
32    return () => observer.disconnect();
33  }, [threshold, root, rootMargin, frozen, freezeOnceVisible]);
34
35  return [ref, entry];
36}
37
38// Advanced lazy loading hook
39function useLazyLoad<T extends HTMLElement = HTMLElement>(
40  onIntersect: () => void,
41  options?: IntersectionObserverInit
42): RefObject<T> {
43  const ref = useRef<T>(null);
44  const callbackRef = useRef(onIntersect);
45  const hasIntersected = useRef(false);
46
47  // Update callback ref
48  useEffect(() => {
49    callbackRef.current = onIntersect;
50  });
51
52  useEffect(() => {
53    const node = ref.current;
54    if (!node || hasIntersected.current) return;
55
56    const observer = new IntersectionObserver(
57      ([entry]) => {
58        if (entry.isIntersecting && !hasIntersected.current) {
59          hasIntersected.current = true;
60          callbackRef.current();
61          observer.disconnect();
62        }
63      },
64      options
65    );
66
67    observer.observe(node);
68    
69    return () => observer.disconnect();
70  }, [options]);
71
72  return ref;
73}
74
75// Usage example
76function LazyImage({ src, alt }: { src: string; alt: string }) {
77  const [imageSrc, setImageSrc] = useState<string>('');
78  const [imageRef, entry] = useIntersectionObserver<HTMLImageElement>({
79    threshold: 0.1,
80    rootMargin: '50px'
81  });
82
83  useEffect(() => {
84    if (entry?.isIntersecting) {
85      // Start loading image when it's about to be visible
86      const img = new Image();
87      img.src = src;
88      img.onload = () => setImageSrc(src);
89    }
90  }, [entry, src]);
91
92  return (
93    <div ref={imageRef} className="lazy-image-container">
94      {imageSrc ? (
95        <img src={imageSrc} alt={alt} />
96      ) : (
97        <div className="placeholder" />
98      )}
99    </div>
100  );
101}
102
103// Infinite scroll example
104function InfiniteList() {
105  const [items, setItems] = useState<number[]>([...Array(20).keys()]);
106  const [loading, setLoading] = useState(false);
107  
108  const loadMoreRef = useLazyLoad(() => {
109    setLoading(true);
110    // Simulate API call
111    setTimeout(() => {
112      setItems(prev => [...prev, ...Array(20).keys()].map((_, i) => i));
113      setLoading(false);
114    }, 1000);
115  }, { rootMargin: '100px' });
116
117  return (
118    <div>
119      {items.map(item => (
120        <div key={item} className="list-item">
121          Item {item}
122        </div>
123      ))}
124      
125      <div ref={loadMoreRef}>
126        {loading ? 'Loading more...' : 'Scroll for more'}
127      </div>
128    </div>
129  );
130}

1// useWindowSize - Responsive window dimensions
2import { useState, useEffect } from 'react';
3
4interface WindowSize {
5  width: number;
6  height: number;
7}
8
9function useWindowSize(debounceMs: number = 0): WindowSize {
10  const [windowSize, setWindowSize] = useState<WindowSize>({
11    width: typeof window !== 'undefined' ? window.innerWidth : 0,
12    height: typeof window !== 'undefined' ? window.innerHeight : 0,
13  });
14
15  useEffect(() => {
16    let timeoutId: NodeJS.Timeout;
17
18    const handleResize = () => {
19      const update = () => {
20        setWindowSize({
21          width: window.innerWidth,
22          height: window.innerHeight,
23        });
24      };
25
26      if (debounceMs > 0) {
27        clearTimeout(timeoutId);
28        timeoutId = setTimeout(update, debounceMs);
29      } else {
30        update();
31      }
32    };
33
34    window.addEventListener('resize', handleResize);
35    
36    // Call handler right away so state gets updated with initial window size
37    handleResize();
38    
39    return () => {
40      window.removeEventListener('resize', handleResize);
41      if (timeoutId) clearTimeout(timeoutId);
42    };
43  }, [debounceMs]);
44
45  return windowSize;
46}
47
48// Media query hook
49function useMediaQuery(query: string): boolean {
50  const [matches, setMatches] = useState(false);
51
52  useEffect(() => {
53    const mediaQuery = window.matchMedia(query);
54    
55    // Set initial value
56    setMatches(mediaQuery.matches);
57
58    // Create listener
59    const listener = (event: MediaQueryListEvent) => {
60      setMatches(event.matches);
61    };
62
63    // Add listener (using addEventListener for better browser support)
64    if (mediaQuery.addEventListener) {
65      mediaQuery.addEventListener('change', listener);
66    } else {
67      mediaQuery.addListener(listener);
68    }
69
70    // Cleanup
71    return () => {
72      if (mediaQuery.removeEventListener) {
73        mediaQuery.removeEventListener('change', listener);
74      } else {
75        mediaQuery.removeListener(listener);
76      }
77    };
78  }, [query]);
79
80  return matches;
81}
82
83// Usage example
84function ResponsiveComponent() {
85  const { width, height } = useWindowSize(200); // 200ms debounce
86  const isMobile = useMediaQuery('(max-width: 768px)');
87  const isTablet = useMediaQuery('(min-width: 769px) and (max-width: 1024px)');
88  const isDesktop = useMediaQuery('(min-width: 1025px)');
89  const prefersDark = useMediaQuery('(prefers-color-scheme: dark)');
90
91  return (
92    <div>
93      <p>Window size: {width} x {height}</p>
94      <p>Device: {isMobile ? 'Mobile' : isTablet ? 'Tablet' : 'Desktop'}</p>
95      <p>Theme preference: {prefersDark ? 'Dark' : 'Light'}</p>
96      
97      {isMobile ? (
98        <MobileLayout />
99      ) : isTablet ? (
100        <TabletLayout />
101      ) : (
102        <DesktopLayout />
103      )}
104    </div>
105  );
106}

1// useScrollPosition - Advanced scroll tracking
2import { useState, useEffect, useCallback, useRef } from 'react';
3
4interface ScrollPosition {
5  x: number;
6  y: number;
7  direction: 'up' | 'down' | 'none';
8  isAtTop: boolean;
9  isAtBottom: boolean;
10}
11
12function useScrollPosition(
13  delay: number = 0,
14  element?: HTMLElement | null
15): ScrollPosition {
16  const [scrollPosition, setScrollPosition] = useState<ScrollPosition>({
17    x: 0,
18    y: 0,
19    direction: 'none',
20    isAtTop: true,
21    isAtBottom: false,
22  });
23  
24  const previousScrollY = useRef(0);
25  const timeoutRef = useRef<NodeJS.Timeout>();
26
27  const handleScroll = useCallback(() => {
28    const updatePosition = () => {
29      const target = element || window;
30      const scrollY = element ? element.scrollTop : window.scrollY;
31      const scrollX = element ? element.scrollLeft : window.scrollX;
32      
33      const scrollHeight = element 
34        ? element.scrollHeight 
35        : document.documentElement.scrollHeight;
36      
37      const clientHeight = element 
38        ? element.clientHeight 
39        : window.innerHeight;
40      
41      const direction = scrollY > previousScrollY.current 
42        ? 'down' 
43        : scrollY < previousScrollY.current 
44        ? 'up' 
45        : 'none';
46      
47      const isAtTop = scrollY === 0;
48      const isAtBottom = scrollY + clientHeight >= scrollHeight - 1;
49      
50      setScrollPosition({
51        x: scrollX,
52        y: scrollY,
53        direction,
54        isAtTop,
55        isAtBottom,
56      });
57      
58      previousScrollY.current = scrollY;
59    };
60
61    if (delay > 0) {
62      clearTimeout(timeoutRef.current);
63      timeoutRef.current = setTimeout(updatePosition, delay);
64    } else {
65      updatePosition();
66    }
67  }, [delay, element]);
68
69  useEffect(() => {
70    const target = element || window;
71    target.addEventListener('scroll', handleScroll, { passive: true });
72    
73    // Initialize
74    handleScroll();
75    
76    return () => {
77      target.removeEventListener('scroll', handleScroll);
78      if (timeoutRef.current) clearTimeout(timeoutRef.current);
79    };
80  }, [handleScroll, element]);
81
82  return scrollPosition;
83}
84
85// Scroll restoration hook
86function useScrollRestoration(key: string) {
87  const scrollPositions = useRef<Map<string, number>>(new Map());
88
89  const saveScrollPosition = useCallback((id: string) => {
90    scrollPositions.current.set(id, window.scrollY);
91    sessionStorage.setItem(`scroll-${key}-${id}`, String(window.scrollY));
92  }, [key]);
93
94  const restoreScrollPosition = useCallback((id: string) => {
95    const savedPosition = sessionStorage.getItem(`scroll-${key}-${id}`);
96    const position = savedPosition 
97      ? parseInt(savedPosition, 10) 
98      : scrollPositions.current.get(id) || 0;
99    
100    window.scrollTo(0, position);
101  }, [key]);
102
103  return { saveScrollPosition, restoreScrollPosition };
104}
105
106// Usage example
107function ScrollAwareHeader() {
108  const { y, direction, isAtTop } = useScrollPosition(50);
109  const [isVisible, setIsVisible] = useState(true);
110
111  useEffect(() => {
112    if (direction === 'down' && y > 100) {
113      setIsVisible(false);
114    } else if (direction === 'up' || isAtTop) {
115      setIsVisible(true);
116    }
117  }, [direction, y, isAtTop]);
118
119  return (
120    <header 
121      className={`header ${isVisible ? 'visible' : 'hidden'}`}
122      style={{
123        transform: `translateY(${isVisible ? '0' : '-100%'})`,
124        transition: 'transform 0.3s ease-in-out',
125        position: 'fixed',
126        top: 0,
127        width: '100%',
128        backgroundColor: isAtTop ? 'transparent' : 'white',
129      }}
130    >
131      <nav>Navigation Content</nav>
132    </header>
133  );
134}