usehooks-ts

Common errors

• TypeError: require is not a function

  cause Attempting to import `usehooks-ts` modules using CommonJS `require()` syntax after the library migrated to ES Modules in v3.0.0.
  fix Update your import statements to use ES Module syntax: `import { HookName } from 'usehooks-ts'`.

• Property 'useDeprecatedHookName' does not exist on type 'typeof import("usehooks-ts")'.

  cause Trying to use a hook that was explicitly removed in `usehooks-ts` v3.0.0 or a later version after being deprecated.
  fix Refer to the `usehooks-ts` documentation to identify the recommended replacement hook (e.g., `useScrollLock` for `useLockedBody`) or implement the desired functionality manually.

• Type 'MyComponentProps' is not assignable to type 'HookParameterType'. Argument of type 'string' is not assignable to parameter of type 'number'.

  cause This usually indicates a type mismatch in arguments passed to hooks, often exacerbated by the library's TypeScript-first approach and strict typing, or changes to internal type aliases in v3.0.0.
  fix Carefully review the type signature of the hook you are using in the `usehooks-ts` documentation. Ensure the values and types you are passing as arguments exactly match the expected types.

Warnings

• breaking Version 3.0.0 of `usehooks-ts` moved its entire workspace to ES Modules. This means direct CommonJS `require()` statements will no longer work, requiring projects to update their import syntax to ES Module standards.
  Fix: Migrate all `require()` statements to `import { HookName } from 'usehooks-ts'` syntax.
• breaking In version 3.0.0, several previously deprecated hooks and their signatures were completely removed. Projects upgrading from versions prior to 3.0.0 might encounter runtime errors if these hooks are still in use.
  Fix: Review release notes for v3.0.0 and update code to use recommended alternatives (e.g., `useScrollLock` instead of `useLockedBody`) or implement custom solutions.
• breaking Version 3.0.0 introduced changes preferring `type` over `interface` for some internal types and renamed or made private certain type aliases. This may cause TypeScript compilation errors in applications that directly reference or extend `usehooks-ts` internal types.
  Fix: Adjust TypeScript code to align with the new type definitions. Consult the `usehooks-ts` documentation or source for updated type names and structures.
• deprecated Several hooks have been deprecated in recent minor versions, with some replaced by new alternatives. For example, `useLockedBody` was replaced by `useScrollLock` (v2.15.0), and `useFetch`, `useEffectOnce`, `useIsFirstRender`, and `useUpdateEffect` were deprecated in v2.14.0.
  Fix: Consult the official `usehooks-ts` documentation for recommended modern alternatives and migrate your codebase accordingly to avoid future breaking changes.
• gotcha While version 3.1.1 officially adds React 19 to its `peerDependencies`, users on older versions of `usehooks-ts` might encounter peer dependency warnings or potential compatibility issues when using React 19.
  Fix: Upgrade to `usehooks-ts@3.1.1` or later to ensure full `peerDependencies` compatibility with React 19. For older versions, ensure your React version is within the specified peer dependency range.

Install

• npm install usehooks-ts npm
• yarn add usehooks-ts yarn
• pnpm add usehooks-ts pnpm

Imports

• useLocalStorage
  wrong:

  const useLocalStorage = require('usehooks-ts').useLocalStorage

  correct:

  import { useLocalStorage } from 'usehooks-ts'

  The library transitioned to ES Modules in v3.0.0, making CommonJS require statements incorrect.
• useBoolean
  wrong:

  import useBoolean from 'usehooks-ts/useBoolean'

  correct:

  import { useBoolean } from 'usehooks-ts'

  All hooks are named exports from the main package entry point.
• useDocumentTitle
  wrong:

  import * as usehooks from 'usehooks-ts'

  correct:

  import { useDocumentTitle } from 'usehooks-ts'

  While star imports work, it's generally recommended to import only the specific hooks you need for optimal tree-shaking.

Quickstart

Demonstrates the basic usage of `useLocalStorage` to persist and manage a counter across browser sessions.

import React from 'react';
import { useLocalStorage } from 'usehooks-ts';

function MyComponent() {
  // Initialize a piece of state in localStorage with a default value of 0
  const [count, setCount] = useLocalStorage('my-counter-key', 0);

  const increment = () => setCount(prev => prev + 1);
  const decrement = () => setCount(prev => prev - 1);
  const reset = () => setCount(0);

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={increment}>Increment</button>
      <button onClick={decrement}>Decrement</button>
      <button onClick={reset}>Reset</button>
    </div>
  );
}

export default MyComponent;