useTimeout

utilities

Installation

npx usehooks-cli@latest add use-timeout

Description

A React hook for managing timeouts with start, stop, reset, and status checking capabilities. Provides fine-grained control over timeout execution and automatically handles cleanup.

Parameters

Name	Type	Default	Description
callback	() => void	-	The function to execute when the timeout completes
delay	number \| null	-	The delay in milliseconds, or null to disable the timeout

Return Type

UseTimeoutReturn

Property	Type	Description
start	() => void	Starts or restarts the timeout
stop	() => void	Stops the timeout and prevents the callback from executing
reset	() => void	Stops the current timeout and starts a new one
isActive	() => boolean	Returns true if the timeout is currently active

Examples

Auto-save Functionality

Implementing auto-save with manual control

const [content, setContent] = useState('');
const [isSaved, setIsSaved] = useState(true);

const saveContent = useCallback(() => {
  // Save content to server
  saveToServer(content);
  setIsSaved(true);
}, [content]);

const { start, stop, reset, isActive } = useTimeout(saveContent, 2000);

const handleContentChange = (newContent: string) => {
  setContent(newContent);
  setIsSaved(false);
  reset(); // Reset the auto-save timer
};

return (
  <div>
    <textarea
      value={content}
      onChange={(e) => handleContentChange(e.target.value)}
    />
    <div>
      {isSaved ? 'Saved' : isActive() ? 'Auto-saving...' : 'Not saved'}
    </div>
    <button onClick={stop}>Cancel Auto-save</button>
  </div>
);

Notification Auto-dismiss

Auto-dismissing notifications with pause/resume

const [notification, setNotification] = useState(null);

const dismissNotification = useCallback(() => {
  setNotification(null);
}, []);

const { start, stop, reset } = useTimeout(dismissNotification, 5000);

const showNotification = (message: string) => {
  setNotification(message);
  reset(); // Start auto-dismiss timer
};

return (
  <div>
    {notification && (
      <div 
        className="notification"
        onMouseEnter={stop} // Pause on hover
        onMouseLeave={start} // Resume on leave
      >
        {notification}
        <button onClick={dismissNotification}>×</button>
      </div>
    )}
  </div>
);

Delayed Action with Cancellation

Implementing delayed actions that can be cancelled

const [isDeleting, setIsDeleting] = useState(false);

const performDelete = useCallback(() => {
  // Perform actual deletion
  deleteItem();
  setIsDeleting(false);
}, []);

const { start, stop, isActive } = useTimeout(performDelete, 3000);

const handleDeleteClick = () => {
  setIsDeleting(true);
  start();
};

const cancelDelete = () => {
  stop();
  setIsDeleting(false);
};

return (
  <div>
    {isDeleting ? (
      <div>
        <p>Deleting in {isActive() ? '3' : '0'} seconds...</p>
        <button onClick={cancelDelete}>Cancel</button>
      </div>
    ) : (
      <button onClick={handleDeleteClick}>Delete Item</button>
    )}
  </div>
);

Dependencies

react

Notes

•Automatically starts the timeout when delay changes (if delay is not null)
•Setting delay to null disables the timeout
•Properly cleans up timeouts on unmount to prevent memory leaks
•The callback ref is updated on each render to ensure latest closure
•Provides both automatic and manual control over timeout execution
•Also exports useTimeoutEffect for simpler automatic timeout behavior

Implementation

"use client";

import { useEffect, useRef, useCallback } from "react";

export interface UseTimeoutReturn {
  start: () => void;
  stop: () => void;
  reset: () => void;
  isActive: () => boolean;
}

export function useTimeout(
  callback: () => void,
  delay: number | null
): UseTimeoutReturn {
  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
  const callbackRef = useRef(callback);

  // Update callback ref when callback changes
  useEffect(() => {
    callbackRef.current = callback;
  }, [callback]);

  const start = useCallback(() => {
    // Clear existing timeout
    if (timeoutRef.current) {
      clearTimeout(timeoutRef.current);
    }

    // Only set timeout if delay is not null
    if (delay !== null) {
      timeoutRef.current = setTimeout(() => {
        callbackRef.current();
        timeoutRef.current = null;
      }, delay);
    }
  }, [delay]);

  const stop = useCallback(() => {
    if (timeoutRef.current) {
      clearTimeout(timeoutRef.current);
      timeoutRef.current = null;
    }
  }, []);

  const reset = useCallback(() => {
    stop();
    start();
  }, [stop, start]);

  const isActive = useCallback(() => {
    return timeoutRef.current !== null;
  }, []);

  // Auto-start timeout when delay changes (if delay is not null)
  useEffect(() => {
    if (delay !== null) {
      start();
    } else {
      stop();
    }

    // Cleanup on unmount or when delay changes
    return stop;
  }, [delay, start, stop]);

  return { start, stop, reset, isActive };
}

// Simplified version that just runs the timeout automatically
export function useTimeoutEffect(
  callback: () => void,
  delay: number | null
): void {
  const callbackRef = useRef(callback);

  // Update callback ref when callback changes
  useEffect(() => {
    callbackRef.current = callback;
  }, [callback]);

  useEffect(() => {
    if (delay === null) {
      return;
    }

    const timeoutId = setTimeout(() => {
      callbackRef.current();
    }, delay);

    return () => clearTimeout(timeoutId);
  }, [delay]);
}

useRoleGuard

CLI Docs All Hooks

useWindowSize