https://custom-react-hooks-live.vercel.app

• Installation
• Hooks List
• Links
• Contributing
• License

Choose and install individual hooks that suit your project needs, or install the entire collection for a full suite of utilities.

If you prefer to have all hooks at your disposal, you can install the entire collection:

npm install @custom-react-hooks/all

or

yarn add @custom-react-hooks/all

Each hook is a standalone package, and you can install them individually using npm or yarn:

npm install @custom-react-hooks/use-async

or

yarn add @custom-react-hooks/use-async

The useExample hook must be imported using a named import as shown below:

Named Import:

import { useExample } from '@custom-react-hooks/use-example';

This approach ensures that the hook integrates seamlessly into your project, maintaining consistency and predictability in how you use our package.

• useAsync
• useClickOutside
• useClipboard
• useDebounce
• useDocumentTitle
• useDragDrop
• useEffectOnce
• useElementSize
• useEventListener
• useFetch
• useForm
• useGeoLocation
• useHover
• useIdle
• useImageLoad
• useKeyPress
• useLockBodyScroll
• useLongPress
• useMediaDevices
• useMediaQuery
• useMouse
• useOnScreen
• useOrientation
• usePermission
• usePortal
• useScript
• useStatus
• useStep
• useStorage
• useThrottle
• useTimeout
• useToggle
• useUpdateEffect
• useWindowSize

• useNetwork
• usePrevious
• useWebSocket
• useCache
• useHistoryState
• useShare
• useWorker
• useIsland
• useOffscreen
• useVirtual

The useAsync hook simplifies the handling of asynchronous operations in React applications, such as data fetching or any other promise-returning functions. It provides a structured way to track the status and outcome of async operations.

• Automated Execution: Optionally executes the async function automatically on component mount.
• Manual Execution: Provides a function to manually trigger the async operation.
• Status and Error Tracking: Tracks the status of the async operation and captures any errors.
• SSR Compatibility: Safe for server-side rendering, with checks to prevent automatic execution on the server.
• Value Management: Manages the value returned from the async operation.

Choose and install individual hooks that suit your project needs, or install the entire collection for a full suite of utilities.

npm install @custom-react-hooks/use-async

or

yarn add @custom-react-hooks/use-async

npm install @custom-react-hooks/all

or

yarn add @custom-react-hooks/all

import React, { useState } from 'react';
import { useAsync } from '@custom-react-hooks/all';

const fetchData = async (endpoint) => {
  const response = await fetch(endpoint);
  if (!response.ok) {
    throw new Error(`Failed to fetch from ${endpoint}`);
  }
  return response.json();
};

const AsyncComponent = () => {
  const [endpoint, setEndpoint] = useState('');
  const [simulateError, setSimulateError] = useState(false);
  const { execute, status, value: data, error } = useAsync(() => fetchData(endpoint), false);

  const handleFetch = () => {
    if (simulateError) {
      setEndpoint('https://jsonplaceholder.typicode.com/todos/1');
    }
    execute();
  };

  return (
    <div>
      <input
        type="text"
        value={endpoint}
        onChange={(e) => setEndpoint(e.target.value)}
        placeholder="Enter API endpoint"
      />
      <button onClick={handleFetch}>Fetch Data</button>
      <div>
        <label>
          <input
            type="checkbox"
            checked={simulateError}
            onChange={() => setSimulateError(!simulateError)}
          />
          Simulate Error
        </label>
      </div>

      {status === 'pending' && <div>Loading...</div>}
      {status === 'error' && <div>Error: {error?.message}</div>}
      {status === 'success' && (
        <div>
          <h3>Data:</h3>
          <pre>{JSON.stringify(data, null, 2)}</pre>
        </div>
      )}
    </div>
  );
};

export default AsyncComponent;

In this example, the useAsync hook is used to perform an asynchronous data fetch operation.

• asyncFunction (Function): The asynchronous function to execute.
• immediate (Boolean, optional): A boolean indicating whether the async function should be executed immediately on component mount. Defaults to false.

An object with the following properties:

• execute (Function): A function to trigger the async operation.
• status (String): The current status of the async operation (idle, pending, success, error).
• value (Any): The value returned from the async operation.
• error (Error | null): Any error that occurred during the execution.

1. API Data Fetching: Fetching data from an API when a component mounts or based on user actions.

2. Form Submission Handling: Managing asynchronous form submissions to a server, including loading states and error handling.

3. Lazy Loading: Dynamically loading components or data based on certain conditions or user interactions.

4. Web API Interactions: Simplifying the use of asynchronous Web APIs (like geolocation or camera access).

5. File Uploads: Handling the asynchronous process of file uploads, including progress tracking and error management.

6. Real-time Data Updates: Managing WebSocket connections or server polling for live data updates.

7. Complex Calculations/Processing: Executing and managing state for asynchronous complex calculations, such as those using Web Workers.

8. Third-party Service Integration: Facilitating interactions with asynchronous third-party services (e.g., payment gateways, social media APIs).

9. Conditional Async Operations: Executing asynchronous tasks based on specific conditions or inputs.

10. Sequencing Async Operations: Coordinating multiple dependent asynchronous operations in sequence.

Contributions to enhance useAsync are highly encouraged. Feel free to submit issues or pull requests to the repository.

The useClickOutside hook is designed to detect and handle clicks outside of a specified element or set of elements. This is particularly useful for closing modal windows, dropdowns, and other components when a user interacts outside of them.

• Element Focus Management: Detects clicks outside of the specified element(s), which is essential for managing the focus and closing modal windows, dropdowns, and other components.
• Customizable Event Listening: Listens for specific events like mousedown and touchstart to determine outside clicks, with the option to customize the events.
• Dynamic Detection Control: Provides the ability to enable or disable the click outside detection dynamically, which offers flexible integration with various UI state requirements.
• Ref Exclusion: Allows for the exclusion of certain elements (by refs) from triggering the outside click logic, which is useful when certain elements within the component should not close it.
• Multiple Element Support: Can handle multiple elements as an array of refs, which is great for complex components that may consist of disjointed elements.
• Simple Integration: Easy to integrate into existing components with minimal changes required to the existing structure.

Choose and install individual hooks that suit your project needs, or install the entire collection for a full suite of utilities.

npm install @custom-react-hooks/use-click-outside

or

yarn add @custom-react-hooks/use-click-outside

npm install @custom-react-hooks/all

or

yarn add @custom-react-hooks/all

Here's an example of how to use the useClickOutside hook in a modal component:

import React, { useState, useRef } from 'react';
import { useClickOutside } from '@custom-react-hooks/all';

const Modal = ({ onClose }) => {
  const modalRef = useRef(null);

  useClickOutside(modalRef, onClose);

  return (
    <div ref={modalRef}>
      <p>Modal content goes here</p>
      <button onClick={onClose}>Close Modal</button>
    </div>
  );
};

const ClickOutsideComponent = () => {
  const [isModalOpen, setModalOpen] = useState(false);

  const openModal = () => setModalOpen(true);
  const closeModal = () => setModalOpen(false);

  return (
    <div>
      <button onClick={openModal}>Open Modal</button>
      {isModalOpen && <Modal onClose={closeModal} />}
    </div>
  );
};

export default ClickOutsideComponent;

In the above example, clicking outside the <div> containing the modal content will trigger the onClose function.

• refs (RefObject | RefObject[]): A ref or an array of refs to the element(s) you want to detect outside clicks on.
• callback (function): A callback function that will be called when a click outside the detected elements occurs.
• events (string[], optional): An array of event names to listen for clicks. Defaults to ['mousedown', 'touchstart'].
• enableDetection (boolean, optional): A boolean to enable or disable click detection. Defaults to true.
• ignoreRefs (RefObject[], optional): An array of ref objects for elements that, when clicked, should not trigger the callback.

• Closing Modals or Popups: Automatically close a modal or popup when a user clicks outside of it.
• Dropdown Menus: Collapse dropdown menus when the user interacts with other parts of the application.
• Context Menus: Hide context menus or custom right-click menus when clicking elsewhere on the page.
• Form Validation or Submission: Trigger form validation or submission when clicking outside of a form area.
• Toggling UI Elements: Toggle the visibility of UI elements like sidebars or tooltips when clicking outside of them.

• Ensure the elements referenced by refs are mounted when the hook is called.
• The hook must be called within a functional component body or another custom hook.

Feel free to contribute to the development of this hook by submitting issues or pull requests to the repository.

useClipboard is a React hook that provides a comprehensive interface for clipboard operations. It offers advanced features like automatic clipboard content reading, change detection, and polling capabilities, making it perfect for building sophisticated clipboard-aware applications.

• Copy and Paste: Offers methods to both copy text to and paste text from the clipboard.
• Clipboard Content Reading: Automatically reads and tracks clipboard content with real-time updates.
• Content Change Detection: Detects when clipboard content changes and provides callbacks.
• Polling Support: Optional polling to continuously monitor clipboard changes.
• Smart State Management: Tracks clipboard content, loading states, and operation status.
• Asynchronous API: Uses promise-based Clipboard API methods for non-blocking operations.
• Status and Error Reporting: Returns the status of clipboard operations and any error messages.
• Server-Side Rendering Compatibility: Checks for the availability of the Clipboard API, ensuring the hook does not break in a server-side rendering context.

Choose and install individual hooks that suit your project needs, or install the entire collection for a full suite of utilities.

npm install @custom-react-hooks/use-clipboard

or

yarn add @custom-react-hooks/use-clipboard

npm install @custom-react-hooks/all

or

yarn add @custom-react-hooks/all

import React, { useState } from 'react';
import { useClipboard } from '@custom-react-hooks/all';

const ClipboardComponent = () => {
  const { 
    copyToClipboard, 
    pasteFromClipboard, 
    state, 
    clipboardContent, 
    hasContent,
    isReading 
  } = useClipboard({
    onClipboardChange: (content) => {
      console.log('Clipboard changed:', content);
    }
  });
  
  const [textToCopy, setTextToCopy] = useState('');

  const handleCopy = async () => {
    await copyToClipboard(textToCopy);
  };

  const handlePaste = async () => {
    const text = await pasteFromClipboard();
    console.log('Pasted:', text);
  };

  return (
    <div>
      <div>
        <input
          type="text"
          value={textToCopy}
          onChange={(e) => setTextToCopy(e.target.value)}
          placeholder="Text to copy"
        />
        <button onClick={handleCopy} disabled={!textToCopy.trim()}>
          Copy to Clipboard
        </button>
      </div>

      <div>
        <button 
          onClick={handlePaste} 
          disabled={!hasContent || isReading}
        >
          {isReading ? 'Reading...' : hasContent ? `Paste (${clipboardContent.substring(0, 20)}...)` : 'Clipboard Empty'}
        </button>
      </div>

      <div>
        <p>Current Clipboard: {clipboardContent || 'Empty'}</p>
        <p>Has Content: {hasContent ? 'Yes' : 'No'}</p>
      </div>

      {state.success && <p>Operation successful!</p>}
      {state.error && <p>Error: {state.error}</p>}
    </div>
  );
};

export default ClipboardComponent;

This example demonstrates the enhanced useClipboard hook with automatic clipboard content reading, smart button states, and change detection.

The useClipboard hook accepts an optional configuration object:

• readOnMount (boolean, optional): Whether to automatically read clipboard content on mount. Default: true.
• pollingInterval (number, optional): Polling interval in milliseconds to check for clipboard changes. Set to 0 to disable polling. Default: 0.
• onClipboardChange (function, optional): Callback fired when clipboard content changes.

• copyToClipboard(text: string): Copies the provided text to the clipboard and updates the local state.
• pasteFromClipboard(): Reads and returns text from the clipboard, updating the local state.
• refreshClipboard(): Manually refreshes the clipboard content without performing a paste operation.
• clearClipboard(): Clears the clipboard by copying a space character.
• state: Object containing success (boolean) and error (string | null) properties.
• clipboardContent: Current content of the clipboard as a string.
• hasContent: Boolean indicating whether the clipboard contains non-empty content.
• isReading: Boolean indicating whether the hook is currently reading from the clipboard.

• Smart Paste Buttons: Create buttons that are enabled/disabled based on clipboard content, as suggested in the GitHub comment.
• Clipboard Monitoring: Monitor clipboard changes for security applications or productivity tools.
• Copy to Clipboard: Copy text like URLs, codes, or user-generated content to the clipboard.
• Paste from Clipboard: Retrieve and use data from the clipboard, useful in form fields or for data import.
• Clipboard Integration in Editors: Use in text editors or note-taking apps for enhanced clipboard interactions.
• Sharing Content: Enable users to easily copy shareable content or links to their clipboard.
• Data Export/Import: Simplify copying and pasting data for export/import operations within an application.
• Clipboard History: Build clipboard history features by tracking clipboard changes over time.
• Content Validation: Validate clipboard content before allowing paste operations.

We encourage contributions to enhance useClipboard. For bugs, feature requests, or pull requests, please reach out through the project's repository.

The useDebounce hook is used to delay the execution of a function until a specified amount of time has passed since it was last invoked. This is useful for handling rapid user input scenarios, such as search input fields or window resizing.

Choose and install individual hooks that suit your project needs, or install the entire collection for a full suite of utilities.

npm install @custom-react-hooks/use-debounce

or

yarn add @custom-react-hooks/use-debounce

npm install @custom-react-hooks/all

or

yarn add @custom-react-hooks/all

• Function Execution Delay: Delays the execution of a function until a certain amount of time has passed since its last invocation, effectively controlling the rate at which the function fires.

• Configurable Delay and Max Wait: Offers the flexibility to set both a delay for the debounce and a maximum waiting time, ensuring the function is executed after a certain period even if the input continues.

• Leading and Trailing Edge Execution: Provides options for executing the function at the start (leading edge) or at the end (trailing edge) of the debounce delay, catering to different use case requirements.

• Improved Performance in Rapid Input Scenarios: Particularly useful in scenarios involving rapid user inputs, such as typing in search fields or adjusting UI elements, to prevent excessive function calls.

• Cancel Functionality: Includes a mechanism to cancel the debounced action, offering additional control over the debounced function's behavior.

• Optimized for User Interaction Scenarios: Ideal for use cases like search inputs, form validations, or any scenario where user input can trigger frequent updates or API calls.

• Versatile Application: Can be used in various scenarios beyond input fields, such as debouncing API calls, resize or scroll event handlers, and more.

• Memory Leak Prevention: Cleans up timeouts on component unmount to prevent memory leaks, ensuring better resource management in React applications.

• Refined User Experience: Enhances user experience by reducing the frequency of potentially disruptive or intensive operations during rapid user interactions.

• Rate-limiting for User Actions: Useful for rate-limiting user actions, preventing excessive or unintended interactions, like rapid button clicks or toggle switches.

Here's an example of using useDebounce in a search input component:

import React, { useState } from 'react';
import { useDebounce } from '@custom-react-hooks/all';

const DebounceComponent = () => {
  const [inputValue, setInputValue] = useState('');
  const [debouncedValue, setDebouncedValue] = useState('');

  const [updateDebouncedValue] = useDebounce(
    (val) => {
      setDebouncedValue(val);
    },
    1000,
    { maxWait: 2000 },
  );

  const handleChange = (e) => {
    const value = e.target.value;
    setInputValue(value);
    updateDebouncedValue(value);
  };

  return (
    <div>
      <input
        type="text"
        value={inputValue}
        onChange={handleChange}
        placeholder="Type here..."
      />
      <p>Debounced Value: {debouncedValue}</p>
    </div>
  );
};

export default DebounceComponent;

In this component, the search function is debounced, which means it will only execute 500 milliseconds after the user stops typing.

• callback (Function): The function to debounce.
• delay (number): The number of milliseconds to delay.
• options (object, optional): Configuration options for the debounce behavior. Options include:
  • maxWait (number): The maximum time the function can be delayed before it's executed, regardless of subsequent calls.
  • leading (boolean): If true, the function is executed on the leading edge of the timeout.
  • trailing (boolean): If true, the function is executed on the trailing edge of the timeout.

• [debouncedFunction, cancelDebounce]:
  • debouncedFunction (Function): The debounced version of the provided function.
  • cancelDebounce (Function): A function that can be called to cancel the debounced action.

• Search Input: Debounce search input to reduce the number of API calls during typing.
• Form Validation: Delay validation until the user has stopped typing, improving performance and user experience.
• Resize or Scroll Events: Improve performance by debouncing window resize or scroll event handlers.
• Autocomplete Fields: Use in autocomplete or typeahead fields to control the rate of server requests.
• Saving User Input: Auto-save user input in a text field or editor with a delay, reducing unnecessary save operations.
• Rate-limiting User Actions: Prevent rapid, repeated actions by the user, like button clicks or toggle switches.

• The useDebounce hook is useful for optimizing performance in scenarios where you want to limit the frequency of function execution.
• Make sure to adjust the delay based on your specific use case.

Your contributions are welcome! Feel free to submit issues or pull requests to improve the useDebounce hook.

useDocumentTitle is a custom React hook for dynamically setting the document title. It updates the title shown in the browser tab, enhancing the user experience by reflecting the current page or content state.

• Dynamic Title Management: Easily update the browser tab title based on the current app state or page.
• Reversion Option: Optionally reverts to the original title when the component unmounts.
• Server-Side Rendering Support: Compatible with SSR by safely checking for the document object.

Choose and install individual hooks that suit your project needs, or install the entire collection for a full suite of utilities.

npm install @custom-react-hooks/use-document-title

or

yarn add @custom-react-hooks/use-document-title

npm install @custom-react-hooks/all

or

yarn add @custom-react-hooks/all

import React, { useState } from 'react';
import { useDocumentTitle } from '@custom-react-hooks/all';

const DocumentTitleComponent = () => {
  const [title, setTitle] = useState('My Awesome Page');
  useDocumentTitle(title);

  return (
    <div>
      <h1>Welcome to My Awesome Page</h1>
      <button
        onClick={(e) => {
          setTitle('Clicked on the button');
        }}
      >
        Click on the button
      </button>
      <button
        onClick={(e) => {
          setTitle('My Awesome Page');
        }}
      >
        Restore title name
      </button>
    </div>
  );
};
export default DocumentTitleComponent;

In this example, the hook is used to set the document title to "My Awesome Page" when DocumentTitleComponent is rendered.

• title: The string to set as the document title.
• revertOnUnmount: (optional) A boolean that determines whether to revert to the original title on component unmount.

• Page Titling: Update the document title based on the current page or view in a Single Page Application (SPA).
• Contextual Information: Show contextual information (like unread message count) in the title.
• Feedback on User Actions: Reflect changes in application state (like a successful form submission).
• SEO Optimization: For server-side rendered applications, dynamically setting titles can help with SEO.

Your contributions to improve useDocumentTitle are appreciated. Feel free to submit issues or pull requests to enhance its functionality and usability.

useDragDrop is a combined React hook that facilitates drag-and-drop interactions in your application. It abstracts the handling of both draggable elements and drop targets, simplifying the implementation of drag-and-drop functionality.

• Combined Drag and Drop Handling: Manages both dragging and dropping within a single hook.
• Customizable Data Transfer: Allows any data to be associated with the drag operation and retrieved upon dropping.
• Event Handling: Abstracts away the complexity of drag-and-drop event management.
• Real-time State Management: Tracks the state of dragging and dropping actions in real-time.
• SSR Compatibility: Designed to be server-side rendering friendly.

Choose and install individual hooks that suit your project needs, or install the entire collection for a full suite of utilities.

npm install @custom-react-hooks/use-drag-drop

or

yarn add @custom-react-hooks/use-drag-drop

npm install @custom-react-hooks/all

or

yarn add @custom-react-hooks/all

import React from 'react';
import { useDragDrop } from '@custom-react-hooks/all';

const DraggableItem = ({ id, bindDrag }) => (
  <div {...bindDrag(id)}>
    {id}
  </div>
);


const DroppableArea = ({ id, bindDrop, children }) => (
  <div {...bindDrop(id)}>
    {children}
  </div>
);

const DragDropComponent = () => {
  const [itemLocations, setItemLocations] = useState({ Item1: 'outside' });

  const handleDrop = (dragId, dropId) => {
    setItemLocations((prev) => ({ ...prev, [dragId]: dropId }));
  };

  const { state, bindDrag, bindDrop } = useDragDrop(handleDrop);

  const renderDraggableItem = (id, location) => {
    return itemLocations[id] === location ? (
      <DraggableItem
        id={id}
        bindDrag={bindDrag}
      />
    ) : null;
  };

  return (
    <div>
      {renderDraggableItem('Item1', 'outside')}

      <div className="btns">
        <DroppableArea
          id="Area1"
          bindDrop={bindDrop}
          isOver={state.isOver && state.overDropId === 'Area1'}
        >
          {renderDraggableItem('Item1', 'Area1')}
        </DroppableArea>

        <DroppableArea
          id="Area2"
          bindDrop={bindDrop}
          isOver={state.isOver && state.overDropId === 'Area2'}
        >
          {renderDraggableItem('Item1', 'Area2')}
        </DroppableArea>
      </div>
    </div>
  );
};

export default DragDropComponent;

In this example, useDragDrop is used to implement both draggable and droppable components.

• useDragDrop(dragData: any, onDrop: (data: any) => void): A function that accepts drag data and a drop callback.

• dragData: The data to be associated with the drag operation.
• onDrop: A callback function that gets executed with the dropped data.

• state: An object containing the current drag and drop states.
• bindDrag: Binding properties for the draggable element.
• bindDrop: Binding properties for the drop target.

• List and Grid Manipulation: Rearrange items in lists or grids via drag and drop.
• File Upload Interfaces: Implement drag-and-drop file upload interfaces.
• Interactive Dashboards: Allow users to customize dashboards by moving widgets or cards.
• Cross-Component Data Transfer: Facilitate data transfer between different parts of the UI.
• Visual Editors: Use in visual editors for dragging elements, layers, or tools.

Contributions to improve useDragDrop are welcome. Please submit issues or pull requests to the repository for any bugs or feature enhancements.

useEffectOnce is a custom hook in React designed to mimic the behavior of componentDidMount and componentWillUnmount lifecycle methods in class components. It's a modified version of useEffect that runs only once when the component mounts.

• Single Execution: The hook executes the provided effect function once upon the component's initial render.
• Cleanup Capability: It supports an optional cleanup function, returned from the effect, which is called when the component unmounts.
• SSR Compatibility: As an extension of useEffect, it is naturally compatible with server-side rendering environments.

Choose and install individual hooks that suit your project needs, or install the entire collection for a full suite of utilities.

npm install @custom-react-hooks/use-effect-once

or

yarn add @custom-react-hooks/use-effect-once

npm install @custom-react-hooks/all

or

yarn add @custom-react-hooks/all

import React from 'react';
import { useEffectOnce } from '@custom-react-hooks/all';

const EffectOnceComponent = () => {
  const [fibonacciSequence, setFibonacciSequence] = useState([]);

  const calculateFibonacci = (n) => {
    let sequence = [0, 1];
    for (let i = 2; i < n; i++) {
      sequence[i] = sequence[i - 1] + sequence[i - 2];
    }
    return sequence.slice(0, n);
  };

  useEffectOnce(() => {
    const sequence = calculateFibonacci(5);
    setFibonacciSequence(sequence);
  });

  return (
    <div>
      <p>First {5} numbers in the Fibonacci sequence:</p>
      <ul>
        {fibonacciSequence.map((number, index) => (
          <li key={index}>{number}</li>
        ))}
      </ul>
    </div>
  );
};

export default EffectOnceComponent;

In this example, useEffectOnce is used to perform actions at the mounting and unmounting phases of MyComponent.

• effect: A function that will be executed once when the component mounts. This function can optionally return a cleanup function, which will be executed when the component unmounts.

• Initial Setup: Perform setup operations like fetching initial data or setting up listeners.
• One-time Calculations: Compute values needed only once during the component's lifecycle.
• Single API Calls: Make a single API call when a component is rendered for the first time.
• Non-Recurring Subscriptions: Subscribe to a service or event listener that should only be initialized once.

Contributions to enhance useEffectOnce are always welcome. Feel free to submit issues or pull requests to the repository for further improvements.

useElementSize is a React hook that enables dynamic tracking of an HTML element's dimensions. It updates the element's width and height in response to window resizing, element mounting/unmounting, and ref changes.

• Dynamic Dimension Tracking: Automatically tracks and updates the width and height of the specified element.
• Responsive to Environmental Changes: Responds to window resizing and ref changes, ensuring accurate size measurements.
• SSR Safe: Compatible with server-side rendering, avoiding errors in environments without a window object.
• Optimized for Accuracy: Uses useLayoutEffect for precise dimension measurements after DOM mutations.

Choose and install individual hooks that suit your project needs, or install the entire collection for a full suite of utilities.

npm install @custom-react-hooks/use-element-size

or

yarn add @custom-react-hooks/use-element-size

npm install @custom-react-hooks/all

or

yarn add @custom-react-hooks/all

import React, { useRef, useState } from 'react';
import { useElementSize } from '@custom-react-hooks/all';

const ElementSizeComponent = () => {
  const [setRef, size] = useElementSize();

  return (
    <div className="element-size">
      <div
        ref={setRef}
        className="resize"
      >
        <p>Drag from the bottom-right corner to resize.</p>
      </div>
      <br />
      <div>Current Size:</div>
      <div className="btns">
        <p>
          Width: <span>{size.width}px</span>
        </p>
        <p>
          Height: <span>{size.height}px</span>
        </p>
      </div>
    </div>
  );
};

export default ElementSizeComponent;

In this example, useElementSize is used to measure and display the dimensions of a div element.

• ref: A React ref object attached to the element whose size you want to measure.

• width: width of the element
• height: height of the element.

• Responsive Components: Adjust component behavior or style based on its size.
• Layout Calculations: Calculate layout for items like grids or masonry layouts that depend on element sizes.
• Size-dependent Rendering: Render different content or components based on available size.
• Animations and Transitions: Trigger animations or transitions when an element's size changes.
• Optimizing Canvas or SVG: Adjust dimensions for canvas or SVG elements based on their container size.

Your contributions to improve useElementSize are welcome. Feel free to submit issues or pull requests to the repository.

The useEventListener hook is a custom React hook that simplifies the process of adding and removing event listeners in your React components. It handles the lifecycle of the event listener, ensuring it is cleaned up when the component unmounts or dependencies change.

npm install @custom-react-hooks/use-event-listener

or

yarn add @custom-react-hooks/use-event-listener

npm install @custom-react-hooks/all

or

yarn add @custom-react-hooks/all

• Effortless Event Handling: Streamlines the process of adding and removing event listeners in React components, making it easier to handle user interactions and other events.

• Automatic Cleanup: Automatically cleans up event listeners when the component unmounts or dependencies change, preventing memory leaks and ensuring optimal performance.

• Support for Multiple Events: Capable of attaching listeners to multiple events simultaneously, making it versatile for handling various types of interactions within a single component.

• Flexible Element Targeting: Offers the ability to attach event listeners to specific DOM elements using a ref, or defaults to the global window object if no element is specified.

• Conditional Event Listening: Includes an optional condition parameter to dynamically attach or detach event listeners based on certain conditions, enhancing the hook's adaptability in different scenarios.

• Custom Event Handling Function: Allows for the specification of a custom handler function for each event, providing full control over the response to the triggered events.

• Option Customization: Supports both boolean and object options for event listeners, aligning with the standard addEventListener API and providing flexibility for more complex event handling requirements.

• Ref Management: Uses a ref to store the current handler function, ensuring that the most recent handler is used and preventing stale closures.

• Event Listener Abstraction: Abstracts the complexities of correctly attaching and detaching event listeners in React's lifecycle, allowing developers to focus on the core logic of their components.

• Versatility in Use: Suitable for a wide range of use cases, from handling user inputs like keyboard and mouse events to responding to browser and device events like resizing and orientation changes.

Here's an example of how to use the useEventListener hook in a component:

import { useEventListener } from '@custom-react-hooks/all';

const EventListenerComponent = () => {
  const [count, setCount] = useState(0);

  const handleKeyDown = (event) => {
    if (event.key === 'ArrowRight') {
      setCount((prevCount) => prevCount + 1);
    } else if (event.key === 'ArrowLeft') {
      setCount((prevCount) => prevCount - 1);
    }
  };

  useEventListener('keydown', handleKeyDown);

  const getColor = () => {
    if (count < 0) return '#ff5868';
    if (count > 0) return '#00989a';
    return '#f9f871';
  };

  return (
    <div>
      <h2>Press the Arrow Left/Right keys to change the counter.</h2>
      <p>(If is not working, click me!)</p>
      <p>
        Counter: <span style={{ color: getColor() }}>{count}</span>
      </p>
    </div>
  );
};

export default EventListenerComponent;

In this component, useEventListener is used to listen for keydown events on the div element, and the state is updated with the last key pressed.

• eventName (string | string[]): The name of the event to listen to, or an array of event names.
• handler (function): The function to be called when the event is triggered.
• element (RefObject, optional): The ref object pointing to the DOM element to which the event listener will be attached. If not provided, the event listener will be attached to the window object.
• options (boolean | AddEventListenerOptions, optional): Options to pass to the event listener.
• condition (boolean, optional): A boolean value to conditionally attach or detach the event listener.

Let's explore the use cases for each of the four additional hooks you've provided:

• Custom Interactions: Capture custom user interactions like keyboard shortcuts or mouse movements.
• Tracking User Behavior: Monitor events for analytics, like clicks or page visibility changes.
• Interactive Components: Enhance components with interactive features, like drag-and-drop or hover effects.
• Window or Document Events: Listen to window resize, scroll, or focus events to adjust UI accordingly.
• Device Capabilities: Detect device capabilities, such as orientation change or network status updates.

• Ensure the element referenced by element is mounted when the hook is called.
• The hook is versatile and can be used for various events and elements within a React application.

Your contributions to the development and enhancement of this hook are welcome! Feel free to submit issues or pull requests to the repository.

The useFetch hook is a powerful tool for making API requests in React applications. It simplifies the process of fetching data from a URL and handles various advanced features like caching, timeouts, and integration with global state management systems.

npm install @custom-react-hooks/use-fetch

or

yarn add @custom-react-hooks/use-fetch

npm install @custom-react-hooks/all

or

yarn add @custom-react-hooks/all

• Automatic Data Fetching: The hook initiates a fetch request as soon as the component mounts, making it effortless to load data from APIs or servers. This behavior can be controlled with the manual option for more specific use cases.

• Manual Fetch Control: Provides the flexibility to manually trigger fetch requests using the fetchData function. This is particularly useful for cases where data needs to be re-fetched based on user interactions or other events.

• Built-in Loading and Error States: Manages loading and error states internally, simplifying the process of rendering different UI components based on the status of the API request.

• Configurable Fetch Options: Extends the standard fetch API options, allowing customization of request headers, method, body, and other settings. This makes it versatile for various types of API requests.

• Timeout Support: Includes a timeout feature, enabling the specification of a maximum time to wait for a response. This helps in handling scenarios where the server response might be delayed.

• Response Caching: Offers an optional caching mechanism to store and retrieve responses. This reduces redundant network requests, optimizing performance for frequently accessed data.

• Global State Integration: Allows for the integration with global state management systems by providing an optional setter function. This is useful for updating global states like Redux or Context API with the fetched data.

• Automatic Cleanup: Handles the cleanup of timeouts and aborts ongoing fetch requests to prevent memory leaks and unwanted side effects, especially important in dynamic and complex applications.

• Error Handling: Captures and returns errors encountered during the fetch process, facilitating robust error handling and user feedback mechanisms in the application.

• Flexible Return Types: The hook is generic, making it capable of returning data in any format (e.g., JSON, text), depending on the needs of the application.

• Server-Side Rendering Compatibility: Designed to be safely used in server-side rendering environments, avoiding errors related to the absence of a window or browser-specific APIs.

Here's an example of how to use the useFetch hook in a component:

import { useFetch } from '@custom-react-hooks/all';

const FetchComponent = () => {
  const [url, setUrl] = useState('https://jsonplaceholder.typicode.com/users/1');
  const { data, loading, error, fetchData } = useFetch(url, { manual: true });

  const handleChange = (event) => {
    setUrl(event.target.value);
  };

  const handleFetch = () => {
    fetchData();
  };

  return (
    <div>
      <input
        type="text"
        value={url}
        onChange={handleChange}
      />
      <button
        onClick={handleFetch}
        disabled={loading}
      >
        Fetch Data
      </button>

      {loading && <p>Loading...</p>}
      {error && <p>Error: {error.message}</p>}
      {data && (
        <div>
          <p>Data:</p>
          <pre>{JSON.stringify(data, null, 2)}</pre>
        </div>
      )}
    </div>
  );
};

export default FetchComponent;

In this example, useFetch is used to load data from an API. The component displays the data, a loading state, and any error that might occur. A button is provided to manually trigger the fetch request.

• url (string): The URL to fetch data from.
• options (RequestInit & { manual?: boolean, timeout?: number }, optional): Configuration options for the fetch request. Includes standard fetch options along with manual for manual trigger and timeout for request timeout.
• cache (Map<string, T> | null, optional): An optional cache object to store and retrieve responses.
• globalStateSetter ((data: T | null) => void, optional): An optional global state setter function for integration with global state management systems.

An object containing:

• data (T | null): The data received from the fetch request.
• loading (boolean): The loading state of the request.
• error (Error | null): Any error encountered during the request.
• fetchData (() => Promise): A function to manually trigger the fetch request.

• Data Fetching: Load data from an API or server, handling loading states and errors.
• Caching Responses: Implement caching strategies to reduce redundant network requests.
• Global State Updates: Update global state (like in Redux or Context API) with fetched data.
• Polling Mechanism: Implement polling for real-time updates from a server.
• Conditional Requests: Make API requests based on user actions or component lifecycle.

• The useFetch hook is designed to be flexible and can be adapted to fit various fetching requirements.
• Remember to handle the cleanup of timeouts and abort controllers to avoid memory leaks and unexpected behavior in your components.

Contributions to enhance the useFetch hook are welcome. Feel free to submit issues or pull requests to the repository.

The useForm hook is an advanced form management tool for React applications, providing capabilities for managing form state, validation, loading status, and submission feedback.

• Flexible Form State Management: Handles values, errors, and touch status of form fields.
• Custom Validation: Supports custom validation logic for form fields.
• Loading State (isSubmitting): Indicates when the form is being submitted, useful for displaying loading indicators.
• Submission Status (submissionStatus): Provides feedback on the form submission process, with states like idle, success, or error.

npm install @custom-react-hooks/use-form

or

yarn add @custom-react-hooks/use-form

npm install @custom-react-hooks/all

or

yarn add @custom-react-hooks/all

• Comprehensive Form State Management: Efficiently manages the state of form fields including values, validation errors, and touched status, ensuring a smooth form handling experience.

• Customizable Validation Logic: Supports custom validation functions, allowing for flexible and complex validation rules tailored to specific form requirements.

• Real-Time Feedback on Form State: Tracks the isSubmitting state, providing real-time feedback on the form's submission process, which is particularly useful for implementing loading indicators.

• Detailed Submission Status Tracking: Maintains a submissionStatus state with values like idle, success, or error, offering precise feedback on the outcome of form submissions.

• Dynamic Form Field Handling: Capable of managing dynamic form fields, allowing for adding, removing, or updating fields as needed within the form.

• Synchronous and Asynchronous Validation: Supports both synchronous and asynchronous validation, making it suitable for a variety of validation scenarios including server-side validation checks.

• Event Handlers for Form Interactions: Provides built-in handlers for common form events like changes (handleChange), blurs (handleBlur), and submissions (handleSubmit), simplifying form interaction logic.

• Form Reset Functionality: Includes a resetForm function to easily reset the form to its initial state, enhancing user experience in scenarios like form cancellation or reinitialization.

• Declarative Form Submission: The handleSubmit function allows for declarative handling of form submissions, including support for asynchronous operations like API calls.

• Enhanced User Experience: Improves user experience by providing immediate feedback on input validation and submission status, reducing user errors and confusion.

• Optimized for Complex Forms: Ideal for handling complex forms, such as multi-step forms or forms with conditional logic, due to its comprehensive state management and flexible validation capabilities.

import React from 'react';
import useForm from '@custom-react-hooks/use-form';

const FormComponent = () => {
  const initialValues = { username: '', email: '' };
  const [submitting, setSubmitting] = useState(false);
  const [submitResult, setSubmitResult] = useState('');

  const validate = (values) => {
    const errors = {};
    if (!values.username) errors.username = 'Username is required';
    if (!values.email) errors.email = 'Email is required';
    return errors;
  };

  const { values, errors, touched, handleChange, handleBlur, handleSubmit, resetForm } = useForm(
    initialValues,
    validate,
  );

  const onSubmit = async () => {
    setSubmitting(true);
    console.log('Form submitted:', values);

    setTimeout(() => {
      setSubmitResult('Form submitted successfully!');
      setSubmitting(false);
    }, 2000);
  };

  return (
    <>
      {submitting && <div>Loading...</div>}
      {!submitting && submitResult && <div>{submitResult}</div>}
      <form
        onSubmit={(e) => handleSubmit(e, onSubmit)}
        className="form"
      >
        <div className="input-field">
          <label htmlFor="username">Username</label>
          <input
            id="username"
            name="username"
            value={values.username}
            onChange={handleChange}
            onBlur={handleBlur}
          />
          {touched.username && errors.username && <span className="error">{errors.username}</span>}
        </div>

        <div className="input-field">
          <label htmlFor="email">Email</label>
          <input
            id="email"
            name="email"
            value={values.email}
            onChange={handleChange}
            onBlur={handleBlur}
          />
          {touched.email && errors.email && <span className="error">{errors.email}</span>}
        </div>

        <div className="pair">
          <button
            type="submit"
            disabled={submitting}
          >
            Submit
          </button>
          <button
            type="button"
            onClick={resetForm}
            disabled={submitting}
          >
            Reset
          </button>
        </div>
      </form>
    </>
  );
};

export default FormComponent;

• initialValues: Object representing the initial state of the form fields.
• validate: Function for custom validation logic, returning error messages for each field.
• values: Object representing the current values of the form fields.
• errors: Object representing validation errors for each field.
• touched: Object indicating which fields have been touched.
• handleChange: Function to handle changes in form fields.
• handleBlur: Function to handle blur events on form fields.
• handleSubmit: Function to handle form submission, including asynchronous operations.
• resetForm: Function to reset the form to its initial state.
• isSubmitting: Boolean indicating the submitting state of the form.
• submissionStatus: String representing the status of the form submission (idle, success, or error).

• Form State Management: Handle input values, errors, and touched fields.
• Dynamic Form Handling: Dynamically add, remove, or update form fields.
• Form Validation: Implement synchronous or asynchronous form validation.
• Form Submission: Manage form submission status and handle submit events.
• Multi-Step Forms: Control multi-step or wizard-like form processes.

Your contributions to further enhance useForm are welcome. Feel free to submit issues or pull requests to the repository.

The useGeoLocation hook is a powerful tool for accessing and monitoring the user's geographical location in React applications. It offers features such as continuous location watching, error handling, and customizable geolocation options.

• Real-Time Location Tracking: Ability to continuously watch the user's location.
• Custom Geolocation Options: Supports customization of geolocation queries, like timeout and accuracy.
• Error Handling: Robust error handling, including cases where geolocation is not supported.

npm install @custom-react-hooks/use-geo-location

or

yarn add @custom-react-hooks/use-geo-location

npm install @custom-react-hooks/all

or

yarn add @custom-react-hooks/all

Import and use the useGeoLocation hook in your React components:

import { useGeoLocation } from '@custom-react-hooks/all';

function GeoLocationComponent() {
  const { loading, coordinates, error, isWatching } = useGeoLocation();

  return (
    <div>
      <h1>GeoLocation Component</h1>
      {loading && <p>Loading...</p>}
      {!loading && error && <p>Error: {error.message}</p>}
      {!loading && !error && coordinates && (
        <div>
          <p>Latitude: {coordinates.latitude}</p>
          <p>Longitude: {coordinates.longitude}</p>
        </div>
      )}
      <p>Watching: {isWatching ? 'Yes' : 'No'}</p>
    </div>
  );
}

export default GeoLocationComponent;

• options: Optional PositionOptions object to configure geolocation queries.
• watch: Boolean flag to continuously watch the user's location.
• coordinates: The current geographical position of the user.
• error: Error object containing details in case of a failure.
• loading: Boolean indicating whether the location data is being fetched.

• User Location Tracking: Get the current location of the user for services like maps or local information.
• Continuous Location Monitoring: Continuously monitor user's location for real-time tracking applications.
• Geofencing: Implement geofencing features, triggering actions when the user enters or leaves a region.
• Location-Based Services: Provide services or content based on the user’s geographical location.
• Error Handling: Manage errors related to geolocation access, like permission denial or unavailable services.

Contributions to improve useGeoLocation are welcome. Feel free to submit issues or pull requests to enhance its functionality.

The useHover hook is a utility for detecting hover interactions in React components. It simplifies the process of tracking when a user's mouse pointer hovers over an element.

• Hover State Management: Tracks hover state of an element.
• Ref-based Implementation: Attaches event listeners using a React ref, ensuring compatibility with React's DOM handling.
• Server-Side Rendering Compatibility: Safe for use in SSR environments by avoiding direct DOM interactions unless the component is mounted in the browser.
• Optimized Event Handling: Uses useCallback to memoize event handlers for performance optimization.

npm install @custom-react-hooks/use-hover

or

yarn add @custom-react-hooks/use-hover

npm install @custom-react-hooks/all

or

yarn add @custom-react-hooks/all

import { useHover } from '@custom-react-hooks/all';

function HoverComponent() {
  const { ref, isHovered } = useHover();

  return (
    <div ref={ref}>
      <h3>
        {isHovered ? 'Hovered' : 'Hover Me!'}
      </h3>
    </div>
  );
}

export default HoverComponent;

In this example, the useHover hook provides a way to determine if a particular div is being hovered.

• ref: A React ref that should be attached to the element you want to monitor for hover.
• isHovered: A boolean state indicating whether the element is currently being hovered.

• UI Feedback: Change styles or display additional information when an element is hovered.
• Dropdown Menus: Show dropdown menus or submenus when a user hovers over a menu item.
• Tooltip Display: Show tooltips on hover for buttons, links, or other UI elements.
• Interactive Elements: Enhance interactivity for elements like cards or images in a gallery.

Contributions to enhance useHover are welcome. Feel free to submit issues or pull requests to the repository.

useIdle is a React hook designed to detect user inactivity or idle time in applications. It triggers a state change after a specified period of inactivity, making it useful for actions like auto-logout or activity pausing.

• Idle Time Detection: Tracks user inactivity and changes state after a set period.
• Activity Monitoring: Resets the idle timer upon user interactions like mouse movement, keypresses, and scrolling.
• SSR Compatibility: Safely handles server-side rendering by checking for the window object.
• Configurable Idle Duration: Allows setting a custom duration to define user inactivity.

npm install @custom-react-hooks/use-idle

or

yarn add @custom-react-hooks/use-idle

npm install @custom-react-hooks/all

or

yarn add @custom-react-hooks/all

import React from 'react';
import { useIdle } from '@custom-react-hooks/all';
import { MoonIcon, SunIcon } from '@heroicons/react/24/solid';


const IdleComponent = () => {
  const isIdle = useIdle(1000);

  return (
    <div className="center">
      {isIdle ? (
        <div className="btns">
          <MoonIcon/>
          <p>Away</p>
        </div>
      ) : (
        <div className="btns">
          <SunIcon/>
          <p>Online</p>
        </div>
      )}
      <br />
      <p>To see the effect, do not move the mouse or touch the keyboard!</p>
    </div>
  );
};

export default IdleComponent;

In this example, the hook is used to detect when the user has been idle for more than 3 seconds.

• idleTime: The time in milliseconds to wait before considering the user as idle.

• Returns a boolean state indicating if the user is idle.

• Auto Logout: Automatically log users out after a period of inactivity for security purposes.
• Pause Background Activities: Pause or reduce background activities like animations or data fetching.
• User Activity Monitoring: Track user activity to understand usage patterns or for analytics.
• Energy Saving: Reduce energy consumption by dimming the screen or reducing resource-intensive tasks.

Contributions to enhance useIdle are welcome. Feel free to submit issues or pull requests to the repository.

useImageLoad is a custom React hook designed to enhance the user experience by efficiently loading images. It supports lazy loading to improve performance and provides detailed status updates during the image loading process.

• Progressive Image Loading: Displays a thumbnail first, followed by the full-resolution image once loaded.
• Lazy Loading Support: Defers the loading of off-screen images until they are needed.
• Detailed Loading States: Tracks the loading state, completion, and any errors that occur.
• SSR Safe: Checks for window object availability to ensure compatibility with server-side rendered applications.
• Cleanup Mechanism: Properly disconnects IntersectionObserver to prevent memory leaks.

npm install @custom-react-hooks/use-image-load

or

yarn add @custom-react-hooks/use-image-load

npm install @custom-react-hooks/all

or

yarn add @custom-react-hooks/all

import { useImageLoad } from '@custom-react-hooks/all';

const ImageLoadComponent = ({ thumbnailSrc, fullSrc }) => {
  const thumbnailOnlyRef = useRef(null);
  const lazyLoadRef = useRef(null);

  const thumbnailOnlyState = useImageLoad({ thumbnailSrc, fullSrc: '' }, thumbnailOnlyRef);
  const lazyLoadState = useImageLoad({ thumbnailSrc, fullSrc, lazyLoad: true }, lazyLoadRef);

  return (
    <div>
      <div>
        <h3>Thumbnail Only</h3>
        {thumbnailOnlyState.isLoading && <p>Loading thumbnail...</p>}
        {thumbnailOnlyState.hasError && <p>Error loading thumbnail.</p>}
        <img
          ref={thumbnailOnlyRef}
          src={thumbnailOnlyState.src}
          alt="Thumbnail Only"
        />
      </div>
      <p>Scroll down to trigger lazy load</p>

      <div>
        <h3>Lazy Loading Image</h3>
        {lazyLoadState.isLoading && <p>Loading image...</p>}
        {lazyLoadState.hasError && <p>Error loading image.</p>}
        <img
          ref={lazyLoadRef}
          src={lazyLoadState.src}
          alt="Lazy Loading"
        />
      </div>
    </div>
  );
};

export default ImageLoadComponent;

• thumbnailSrc: The source path of the thumbnail image.
• fullSrc: The source path of the full-resolution image.
• lazyLoad: (optional) A boolean to enable lazy loading.

• src: The current source of the image.
• isLoading: Indicates if the image is currently loading.
• isLoaded: Indicates if the image has fully loaded.
• hasError: Indicates if there was an error during loading.

• Progressive Image Loading: Show a low-quality image or placeholder while the full image loads.
• Lazy Loading: Load images only when they are in or near the viewport, improving page load times.
• Error Handling: Handle image load errors gracefully with fallbacks or error messages.
• Loading State Indicators: Display a loading indicator while images are being fetched.

We welcome contributions to useImageLoad. For bugs, feature requests, or pull requests, please reach out through the project's repository.

The useKeyPress hook is an advanced utility for detecting specific keypress events in React applications. It supports customizable debounce timing and can listen for keypress events either globally or locally within a component.

• Key Detection: Monitors for the press of a specific key.
• Debounce Support: Includes an optional debounce feature to manage rapid keypresses.
• Global and Local Listening: Option to listen for keypress events globally (across the entire window) or locally (within a specific component).
• SSR Compatibility: Safely handles server-side rendering environments.

npm install @custom-react-hooks/use-key-press

or

yarn add @custom-react-hooks/use-key-press

npm install @custom-react-hooks/all

or

yarn add @custom-react-hooks/all

import { useKeyPress } from '@custom-react-hooks/all';

const KeyPressComponent = () => {
  const isPressed = useKeyPress('Enter');

  return (
    <div>
      <p>Press the "Enter" key</p>
      <button>
        Enter
      </button>
      {isPressed && <p>You are pressing the "Enter" key!</p>}
    </div>
  );
};

export default KeyPressComponent;

This example demonstrates using useKeyPress to detect when the Enter key is pressed with a debounce of 200 milliseconds.

• targetKey: The key for which the press event should be detected.
• options: An object that may contain:
• debounce: Optional number specifying the debounce time in milliseconds.
• global: Optional boolean indicating whether to listen for the event globally.

• Returns a boolean state indicating whether the specified key is currently pressed.

• Keyboard Shortcuts: Implement custom keyboard shortcuts for enhanced user interaction.
• Game Controls: Handle key presses for browser-based games.
• Navigation: Navigate through components or pages using keyboard keys.
• Accessibility Enhancements: Improve accessibility by providing keyboard interactions.

We welcome contributions to improve useKeyPress. Feel free to submit issues or pull requests to the repository.

useLockBodyScroll is a React hook for controlling the scroll behavior of the body element in web applications. It's particularly useful for scenarios like opening modals or overlays where background scroll needs to be disabled.

• Conditional Scroll Lock: Allows you to conditionally enable or disable the body scroll.
• Style Preservation: Preserves the original body overflow style and restores it upon unmounting.
• Server-Side Rendering (SSR) Compatibility: Safe for use in SSR environments by checking for the document object.
• Synchronous Execution: Uses useLayoutEffect for synchronous updates to the DOM.

npm install @custom-react-hooks/use-lock-body-scroll

or

yarn add @custom-react-hooks/use-lock-body-scroll

npm install @custom-react-hooks/all

or

yarn add @custom-react-hooks/all

import React, { useState } from 'react';
import { useLockBodyScroll } from '@custom-react-hooks/all';

const LockBodyScrollComponent= () => {
  const [isModalOpen, setIsModalOpen] = useState(false);
  useLockBodyScroll(isModalOpen);

  return (
    <div>
      <p>{isModalOpen ? 'Scroll hidden' : 'When you click on the button scroll will be hidden'}</p>
      <button onClick={() => setIsModalOpen(true)}>Open Modal</button>
      {isModalOpen && (
        <div className="modal">
          <div>
            <p>Modal Content</p>
            <button onClick={() => setIsModalOpen(false)}>Close Modal</button>
          </div>
        </div>
      )}
    </div>
  );
};

export default LockBodyScrollComponent;

In this example, the hook is used to lock the body scroll when the modal is open.

• lock: A boolean indicating whether to lock (true) or unlock (false) the body scroll.

1. Modals and Popups: This is the most common use case. When a modal or popup is opened, it's often desirable to lock the background content to prevent the user from scrolling. This keeps the focus on the modal content.

2. Full-Screen Menus: In mobile-responsive designs or certain desktop layouts, when a full-screen menu is opened, you might want to lock the scroll to keep the user's focus on the navigation options.

3. Onboarding Flows or Guided Tours: If your application has a step-by-step onboarding process or a guided tour, you might want to lock scrolling to ensure the user follows the flow without distractions.

4. Image or Video Galleries: When a user clicks on an image or video to view it in a larger format (like a lightbox), locking the scroll can enhance the viewing experience by removing background distractions.

5. Infinite Scroll Prevention: In some scenarios, you might want to temporarily disable infinite scrolling features. For example, when a user performs an action that requires attention or confirmation, you could lock the scroll to keep them focused on the task.

6. Interactive Games or Quizzes: If you're embedding games or quizzes in your web application, you might want to lock the background scroll when these elements are in focus to enhance user engagement and prevent accidental scroll-offs.

7. Alerts or Critical Notifications: When displaying critical alerts or notifications that require immediate attention or action, disabling the background scroll can ensure that the user addresses these alerts without distraction.

8. Complex Forms or Surveys: In a long, multi-step form or survey, you may want to lock the scroll when displaying validation errors or important information to ensure the user sees and acknowledges these messages.

Your contributions to improve useLockBodyScroll are welcome. Feel free to submit issues or pull requests to the repository.

The useLongPress hook is designed for adding long press interactions to elements in React applications. It provides a flexible way to handle long press events with customizable thresholds and callbacks.

• Customizable Long Press Duration: Set a threshold for how long the press should last to trigger the event.
• Multiple Event Callbacks: Options for onStart, onFinish, and onCancel callbacks.
• Support for Mouse and Touch: Works with both mouse and touch events.
• SSR Safe: Can be safely used in server-side rendered applications.

npm install @custom-react-hooks/use-long-press

or

yarn add @custom-react-hooks/use-long-press

npm install @custom-react-hooks/all

or

yarn add @custom-react-hooks/all

import React, { useState } from 'react';
import { useLongPress } from '@custom-react-hooks/all';

const LongPressTestComponent = () => {
  const [status, setStatus] = useState('Ready');

  const longPressCallback = () => {
    setStatus('Finished');
  };

  const longPressEvents = useLongPress(longPressCallback, {
    threshold: 500,
    onStart: () => setStatus('Started'),
    onFinish: () => setStatus('Finished'),
    onCancel: () => setStatus('Cancelled'),
  });

  return (
    <div>
      <button {...longPressEvents}>
        Press and Hold
      </button>
      <p>
        Status: <span>{status}</span>
      </p>
    </div>
  );
};

export default LongPressTestComponent;

This example demonstrates how to use the useLongPress hook to add a long press interaction to a button element.

• callback: The function to execute when a long press event is successfully detected.
• options: Configuration object with the following optional properties:
  • threshold: Time in milliseconds the user must press and hold to trigger a long press event.
  • onStart: Function called when the user starts pressing.
  • onFinish: Function called when a long press event finishes successfully.
  • onCancel: Function called when a press event is cancelled.

• onMouseDown: Event handler for mouse down event to start detecting long press.
• onMouseUp: Event handler for mouse up event to cancel long press detection.
• onMouseLeave: Event handler for mouse leave event to cancel long press detection.
• onTouchStart: Event handler for touch start event to start detecting long press.
• onTouchEnd: Event handler for touch end event to cancel long press detection.

• Mobile Interaction: Implement long press interactions common in mobile interfaces.
• Context Menus: Display custom context menus on long press.
• Drag-and-Drop Initiation: Start a drag-and-drop process after a long press.
• Gesture Recognition: Recognize specific user gestures for advanced UI interactions.

Your contributions to improve useLongPress are appreciated. Feel free to submit issues or pull requests to the repository.

useMediaDevices is a React hook that offers an easy way to access and monitor media devices like cameras, microphones, and speakers. It not only lists all available media input and output devices but also manages user permissions to retrieve detailed device information.

• Device Enumeration: Enumerates all available media devices with details like labels, kinds, and IDs.
• Optional Permission Handling: Optionally prompts the user for access to media devices to retrieve full device information.
• Loading State: Provides a loading state indicating the process of retrieving media devices.
• Error Handling: Offers comprehensive error handling if media devices cannot be accessed or are not available.
• Server-Side Rendering (SSR) Compatibility: Designed to be safely executed in a server-side rendering environment, gracefully handling the absence of browser-specific APIs.

npm install @custom-react-hooks/use-media-devices

or

yarn add @custom-react-hooks/use-media-devices

npm install @custom-react-hooks/all

or

yarn add @custom-react-hooks/all

import React from 'react';
import { useMediaDevices } from '@custom-react-hooks/all';

const MediaDevicesComponent = () => {
  const { devices, isLoading, error } = useMediaDevices(false);

  if (isLoading) {
    return <div>Loading devices...</div>;
  }

  if (error) {
    return <div>Error: {error}</div>;
  }

  return (
    <div className="media-devices">
      <h2>Available Media Devices</h2>
      {devices.length === 0 ? (
        <div>No devices found.</div>
      ) : (
        <ul>
          {devices.map((device) => (
            <li key={device.id}>
              <strong>{device.kind}:</strong> {device.label}
            </li>
          ))}
        </ul>
      )}
    </div>
  );
};

export default MediaDevicesComponent;

In this example, useMediaDevices(true) is used to request user permission and list all available media devices.

• requestPermission (optional, default = false): A boolean parameter that, when set to true, prompts the user for permission to access media devices such as the camera and microphone. If false, the hook will only list the available devices without requesting access.

• devices: An array of MediaDevice objects, each representing an available media device. Each MediaDevice object contains the following properties:
  • id: A string representing the unique identifier of the device.
  • kind: A string indicating the type of the device (e.g., 'videoinput', 'audioinput', 'audiooutput').
  • label: A string representing the label of the device, or 'Unknown Device' if the label is unavailable.
• isLoading: A boolean indicating whether the hook is currently in the process of loading the list of media devices.
• error: A string representing an error message if an error occurred while fetching the list of devices, or null if no error occurred.

• Device Selection: Let users select from available input/output devices for media capture.
• Feature Accessibility: Check for the availability of media devices for features like video calls.
• Dynamic Device Updates: Update the UI when new devices are connected or disconnected.
• Permission Management: Manage user permissions for accessing media devices.

We welcome contributions to enhance useMediaDevices. For bug reports or feature suggestions, please open issues or submit pull requests to our repository.

The useMediaQuery hook is designed for responsive design in React applications. It enables components to adapt to different screen sizes or respond to media query changes.

• Dynamic Media Queries: Accepts any valid CSS media query string.
• SSR Compatibility: Safe for server-side rendering, as it checks for the availability of the window object.
• Efficient and Optimized: Only updates component state when media query match status changes.

npm install @custom-react-hooks/use-media-query

or

yarn add @custom-react-hooks/use-media-query

npm install @custom-react-hooks/all

or

yarn add @custom-react-hooks/all

Import and use the useMediaQuery hook in your React components:

import { useMediaQuery } from '@custom-react-hooks/all';

const MediaQueryComponent = () => {
  const isWide = useMediaQuery('(min-width: 600px)');

  return (
    <div>
      {isWide ? 'Wide viewport detected' : 'Narrow viewport detected'}
      <br />
      <span>
        <i>Resize to see the effect</i>
      </span>
    </div>
  );
};

export default MediaQueryComponent;

• query: A string representing the media query to evaluate.

• Responsive Design: Dynamically adjust the layout or functionality based on viewport size.
• Dark Mode Toggle: Switch between light and dark themes based on user's system preferences.
• Adaptive Rendering: Render different components or content based on media query matches.
• Performance Optimization: Load resources conditionally based on the media query (e.g., images for mobile).

Contributions to enhance the useMediaQuery hook are welcome. Feel free to submit issues or pull requests to the repository.

The useMouse hook is designed for tracking the mouse position within a specified element in React applications. It's enhanced to provide additional features such as offsetting the mouse position and avoiding edges of the screen, which is useful for tooltips and other floating elements.

• Dynamic Mouse Position Tracking: Captures the mouse's x and y coordinates within the target element.
• Offset and Edge Avoidance: Supports offsetting the mouse position and adjusting it to avoid going off the screen edges.
• TypeScript Support: Strongly typed for better integration with TypeScript projects.
• Flexible and Customizable: Provides options for customizing offset values and tooltip dimensions.

npm install @custom-react-hooks/use-mouse

or

yarn add @custom-react-hooks/use-mouse

npm install @custom-react-hooks/all

or

yarn add @custom-react-hooks/all

import React, { useRef } from 'react';
import { useMouse } from '@custom-react-hooks/all';

const Tooltip = ({ mousePosition, isVisible }) => {
  const { window, document } = useFrame();
  const tooltipRef = useRef(null);

  const positionStyles = useMemo(() => {
    const style = { display: isVisible ? 'block' : 'none' };

    if (tooltipRef.current) {
      const tooltipRect = tooltipRef.current.getBoundingClientRect();

      let newX = mousePosition.x;
      let newY = mousePosition.y;

      if (newX + tooltipRect.width > window.innerWidth) {
        newX -= tooltipRect.width;
      }

      if (newY + tooltipRect.height > window.innerHeight) {
        newY -= tooltipRect.height;
      }

      style.left = `${newX}px`;
      style.top = `${newY}px`;
    }

    return style;
  }, [mousePosition, isVisible]);

  return (
    <div
      ref={tooltipRef}
      style={positionStyles}
    >
      X: <span>{mousePosition.x}</span>,
      Y: <span>{mousePosition.y}</span>
    </div>
  );
};

const MouseComponent = () => {
  const boxRef = useRef(null);
  const [isTooltipVisible, setIsTooltipVisible] = useState(false);
  const tooltipOptions = {
    offsetX: 15,
    offsetY: 15,
    avoidEdges: true,
    tooltipWidth: 120,
    tooltipHeight: 50,
  };
  const mousePosition = useMouse(boxRef, tooltipOptions);

  const handleMouseEnter = () => setIsTooltipVisible(true);
  const handleMouseLeave = () => setIsTooltipVisible(false);

  return (
    <div className="center">
      <div
        ref={boxRef}
        onMouseEnter={handleMouseEnter}
        onMouseLeave={handleMouseLeave}
      >
        Hover over this box
      </div>
      <Tooltip
        mousePosition={mousePosition}
        isVisible={isTooltipVisible}
      />
    </div>
  );
};

export default MouseComponent;

In this TypeScript example, the useMouse hook is used to track the mouse position within a div element and adjust the position of a tooltip or pop-up element accordingly.

• ref: A React RefObject pointing to the target element that the mouse position will be relative to.
• options: Configuration object for the mouse position adjustments with the following properties:
  • offsetX: The horizontal offset added to the mouse position.
  • offsetY: The vertical offset added to the mouse position.
  • avoidEdges: Boolean that indicates whether the tooltip position should be adjusted to avoid the edges of the screen or the target element.
  • tooltipWidth: (Optional) The width of the tooltip element, used in calculating edge avoidance.
  • tooltipHeight: (Optional) The height of the tooltip element, used in calculating edge avoidance.
  • relativeToWindow: (Optional) Boolean that indicates whether the mouse position should be calculated relative to the window instead of the target element. If not provided, it defaults to false.

• An object containing the adjusted mouse position and additional information:
  • x: The calculated x-coordinate for the tooltip position.
  • y: The calculated y-coordinate for the tooltip position.
  • position: A string indicating the tooltip's position relative to the cursor. Possible values are 'bottomRight', 'bottomLeft', 'topRight', and 'topLeft'.

• Custom Tooltips: Display tooltips that follow the mouse cursor.
• Interactive Canvas: Implement interactive features on a canvas element based on mouse position.
• UI Enhancements: Enhance UI elements with mouse-over effects or interactions.
• Mouse Tracking: Track mouse movements for user behavior analysis or interactive games.

Contributions to enhance useMouse are welcome. Please feel free to submit issues or pull requests to the repository.

The useOnScreen hook utilizes the Intersection Observer API to detect if an element is visible within the viewport. It's ideal for scenarios such as lazy loading images, triggering animations on scroll, and implementing features like infinite scroll.

• Visibility Detection: Determines if an element is currently visible in the viewport.
• Memoization of Observer: Efficient use of resources by memoizing the Intersection Observer instance.
• One-time Observation: Option to unobserve the element after it becomes visible for the first time.
• Customizable Observer Options: Supports threshold, root, and root margin options for the observer.

npm install @custom-react-hooks/use-on-screen

or

yarn add @custom-react-hooks/use-on-screen

npm install @custom-react-hooks/all

or

yarn add @custom-react-hooks/all

Import and use the useOnScreen hook in your React components. You can also specify whether the element should be unobserved after first being visible by setting the once parameter.

import { useOnScreen } from '@custom-react-hooks/all';

const OnScreenComponent = () => {
  const { ref, isIntersecting } = useOnScreen({ threshold: 1 }, false);

  return (
    <div ref={ref}>
      {isIntersecting ? 'Element is visible!' : 'Scroll down...'}
    </div>
  );
};

export default OnScreenComponent;

• options: Optional IntersectionObserverInit object to customize the observer.
• once: Boolean flag indicating if the element should be unobserved after it becomes visible for the first time.

• ref: Ref object to be attached to the element you want to observe.
• isIntersecting: Boolean indicating whether the observed element is in the viewport.

• Lazy Loading: Load content (like images or videos) only when they enter the viewport.
• Animation on Scroll: Trigger animations or transitions when an element comes into view.
• Infinite Scrolling: Load more content as the user scrolls down a page.
• Visibility Tracking: Track which components are visible on the screen for analytics.

Your contributions to enhance useOnScreen are highly appreciated. Feel free to submit issues or pull requests to improve its functionality and performance.

The useOrientation hook is designed for both React web and mobile applications, providing a comprehensive solution to monitor and respond to orientation changes. This hook can track the orientation of the device or a specific HTML element, offering valuable data for responsive and dynamic UIs.

• Dynamic Orientation Tracking: Continuously updates with the device's current orientation angle and type, as well as the orientation of a specified element.
• Versatile Usage: Capable of tracking either the device's window or a specified element's orientation.
• Detailed Information: Provides orientation angle, type (landscape or portrait), aspect ratio, and orientation state of the referenced element.
• Server-Side Rendering (SSR) Compatibility: Handles environments without a window object, making it suitable for server-side rendering.

npm install @custom-react-hooks/use-orientation

or

yarn add @custom-react-hooks/use-orientation

npm install @custom-react-hooks/all

or

yarn add @custom-react-hooks/all

import React, { useRef } from 'react';
import { useOrientation } from '@custom-react-hooks/all';

const OrientationComponent = () => {
  const elementRef1 = useRef(null);
  const elementRef2 = useRef(null);

  const elementOrientation1 = useOrientation(elementRef1, false);
  const elementOrientation2 = useOrientation(elementRef2, false);
  const windowOrientation = useOrientation(undefined, true);

  return (
    <div>
      <div ref={elementRef1}>
        <strong>Element 1: </strong> {elementOrientation1.elementOrientation}
        <br />
        <strong>Aspect Ratio:</strong>
        {elementOrientation1.aspectRatio ? elementOrientation1.aspectRatio.toFixed(2) : 0}
      </div>
      <div ref={elementRef2}>
        <strong>Element 2: </strong>
        {elementOrientation2.elementOrientation}
        <br />
        <strong>Aspect Ratio:</strong>
        {elementOrientation2.aspectRatio ? elementOrientation2.aspectRatio.toFixed(2) : 0}
      </div>
      <p>Window Orientation: {windowOrientation.type}</p>
    </div>
  );
};

export default OrientationComponent;

In this example, the useOrientation hook is used to monitor the orientation of both the device's window and a specific image element.

• elementRef (Optional): A React RefObject to an HTML element.
• trackWindow (Optional): Boolean to track the device's window orientation.

• angle: The current orientation angle of the device or element in degrees.
• type: The orientation type ('landscape-primary', 'landscape-secondary', 'portrait-primary', 'portrait-secondary').
• aspectRatio: The aspect ratio of the referenced element (if provided).
• elementOrientation: The orientation of the referenced element ('landscape' or 'portrait').

• Responsive Design: Adjust layouts and UI elements based on device orientation.
• Device Orientation Features: Implement features that depend on device orientation, like games or 3D views.
• Element-Specific Orientation: Change the functionality or display of specific elements based on their orientation.
• Aspect Ratio Detection: Detect and respond to changes in the aspect ratio of an element.

We welcome contributions to improve useOrientation. Feel free to submit issues or pull requests to the repository for enhancements, bug fixes, or documentation improvements.

usePermission is a React hook designed to query and monitor the status of user permissions for various browser APIs such as geolocation, notifications, microphone, and camera.

• Permission Querying: Queries the status of a specified permission.
• Real-time Updates: Monitors and updates the permission status in real-time if it changes.
• Error Handling: Provides error messages if the Permissions API is not supported or if an error occurs during the query.
• SSR Compatibility: Executes safely in a server-side rendering environment by avoiding direct browser API calls during SSR.

npm install @custom-react-hooks/use-permission

or

yarn add @custom-react-hooks/use-permission

npm install @custom-react-hooks/all

or

yarn add @custom-react-hooks/all

import React, { useState } from 'react';
import { usePermission } from '@custom-react-hooks/all';

const PermissionComponent = () => {
  const [selectedPermission, setSelectedPermission] = useState('geolocation');
  const { state, isLoading, error } = usePermission(selectedPermission);

  return (
    <div>
      <h2>Check Browser Permission Status</h2>
      <label htmlFor="permission-select">Choose a permission: </label>
      <select
        id="permission-select"
        value={selectedPermission}
        onChange={(e) => setSelectedPermission(e.target.value)}
      >
        <option value="geolocation">Geolocation</option>
        <option value="notifications">Notifications</option>
        <option value="microphone">Microphone</option>
        <option value="camera">Camera</option>
      </select>

      <div>
        {isLoading ? (
          <p>Loading...</p>
        ) : (
          <p>
            Permission status for {selectedPermission}:
            <span> {state}</span>
          </p>
        )}
        {error && <p>Error: {error}</p>}
      </div>
    </div>
  );
};

export default PermissionComponent;