React Use Hooks Collection

Common errors

• Error: Invalid hook call. Hooks can only be called inside of the body of a function component.

  cause Attempting to call a `react-use` hook outside of a React functional component or a custom hook, violating the Rules of Hooks.
  fix Ensure all calls to `use*` functions adhere to the Rules of Hooks by being placed at the top level of React function components or custom hooks.

• TypeError: (0, react_use__WEBPACK_IMPORTED_MODULE_2__.useSomeHook) is not a function

  cause This error typically occurs when attempting to import hooks using CommonJS `require()` syntax or an incorrect named import in an environment expecting ES modules, or if tree-shaking removed the export unexpectedly.
  fix Always use ES module named import syntax: `import { useSomeHook } from 'react-use';`. Verify your build configuration supports ES modules correctly.

• Type 'FC<Props>' is not assignable to type 'FunctionComponent<Props>'

  cause This TypeScript error indicates a compatibility issue between an older version of `react-use` and `@types/react` v18 or newer, where the generic type argument for `React.FC` was deprecated.
  fix Upgrade `react-use` to version 17.3.3 or newer to get the necessary type definition updates compatible with `@types/react` v18.

Warnings

• breaking When upgrading your project's `@types/react` to v18 (or newer), you may encounter TypeScript compilation errors related to `React.FC` (FunctionComponent) type arguments. Specifically, `React.FC` no longer accepts a generic type parameter in `@types/react` v18.
  Fix: Upgrade `react-use` to version 17.3.3 or higher. This version includes a fix that resolves compatibility issues with `@types/react` v18.
• gotcha Hooks relying on browser-specific APIs (e.g., `useMedia`, `useWindowSize`, `useGeolocation`) can cause hydration mismatches or errors when used in Server-Side Rendering (SSR) environments if their initial state is not handled correctly or doesn't match the client-side render.
  Fix: For hooks with potential SSR issues, consider providing a `defaultState` if the hook supports it, or conditionally rendering components that use these hooks only on the client-side (e.g., using `typeof window !== 'undefined'`). Upgrade to `react-use` v17.3.2+ for specific `useMedia` SSR fixes.
• gotcha Incorrectly resolved `react` and `react-dom` peer dependencies can lead to runtime errors or multiple instances of React, causing unpredictable behavior. This can occur if your project's React version doesn't satisfy `react-use`'s peer dependency range.
  Fix: Ensure your project's `react` and `react-dom` versions (e.g., `^17.0.0` or `^18.0.0`) are compatible with the `react-use` peer dependency range defined in `package.json`. Use `npm ls react` and `npm ls react-dom` to inspect installed versions.

Install

• npm install react-use npm
• yarn add react-use yarn
• pnpm add react-use pnpm

Imports

• useWindowSize
  wrong:

  const { useWindowSize } = require('react-use');

  correct:

  import { useWindowSize } from 'react-use';

  react-use primarily uses named exports and is designed for ES modules. CommonJS `require` syntax is generally incorrect or may not work as expected in modern bundlers.
• useBattery
  wrong:

  import useBattery from 'react-use';

  correct:

  import { useBattery } from 'react-use';

  All hooks are named exports; there is no default export from the 'react-use' package. Importing a non-existent default export will result in `undefined`.
• useToggle
  wrong:

  import * as ReactUse from 'react-use'; // then ReactUse.useToggle

  correct:

  import { useToggle } from 'react-use';

  While `import * as` works, directly importing specific named exports is recommended for better tree-shaking and explicit dependency management.
• useStateList

  import { useStateList } from 'react-use';

  TypeScript users will benefit from the included type definitions for all hooks, providing strong typing for hook arguments and return values.

Quickstart

This quickstart demonstrates how to use `useWindowSize` to track browser dimensions, `useBattery` to monitor device battery status, and `useToggle` for simple boolean state management and conditional UI rendering within a React functional component.

import React from 'react';
import { useWindowSize, useBattery, useToggle } from 'react-use';

const App = () => {
  const { width, height } = useWindowSize();
  const batteryState = useBattery();
  const [isVisible, toggleVisibility] = useToggle(true);

  return (
    <div style={{ padding: '20px', fontFamily: 'sans-serif' }}>
      <h1>react-use Quickstart</h1>
      <p>Window Size: {width}px x {height}px</p>

      {batteryState.isSupported ? (
        <p>
          Battery Level: {((batteryState.level ?? 0) * 100).toFixed(0)}%
          {batteryState.charging ? ' (Charging)' : ' (Discharging)'}
        </p>
      ) : (
        <p>Battery status not supported on this device.</p>
      )}

      <button onClick={() => toggleVisibility()} style={{ marginTop: '15px', padding: '8px 12px', cursor: 'pointer' }}>
        {isVisible ? 'Hide' : 'Show'} Toggled Content
      </button>

      {isVisible && (
        <div style={{ marginTop: '15px', border: '1px dashed #ccc', padding: '10px', borderRadius: '4px' }}>
          <p>This content is toggled!</p>
          <p>Current Time: {new Date().toLocaleTimeString()}</p>
        </div>
      )}
    </div>
  );
};

export default App;