Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
useWindowSize
✓ import { useWindowSize } from 'react-use';
✗ const { useWindowSize } = require('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
✓ import { useBattery } from 'react-use';
✗ 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
✓ import { useToggle } from 'react-use';
✗ import * as ReactUse from 'react-use'; // then ReactUse.useToggle
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.
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;
Debug
Known issues
breakingWhen 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.fixUpgrade `react-use` to version 17.3.3 or higher. This version includes a fix that resolves compatibility issues with `@types/react` v18.
affects: <17.3.3
gotchaHooks 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.fixFor 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.
affects: prior to 17.3.2 (fixed for `useMedia` specifically)
gotchaIncorrectly 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.fixEnsure 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.
affects: >=1.0.0
Errors
Common errors & fixes
Error: Invalid hook call. Hooks can only be called inside of the body of a function component.
Attempting to call a `react-use` hook outside of a React functional component or a custom hook, violating the Rules of Hooks.
fixEnsure 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
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.
fixAlways 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>'
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.
fixUpgrade `react-use` to version 17.3.3 or newer to get the necessary type definition updates compatible with `@types/react` v18.
Audit
Dependencies
reactrequiredCore React library is required for all hooks to function.
react-domrequiredNecessary for hooks that interact with the DOM or require React's rendering capabilities.