usehooks-ts: a TypeScript React hook library you install with npm i usehooks-ts

The problem usehooks-ts solves, and who it is for

Every React app accumulates the same small effects: subscribing to a media query, debouncing a search input, persisting a value to localStorage, attaching a window listener without leaking it on unmount. Each one is short enough that people write it inline, and subtle enough that they get the cleanup wrong. usehooks-ts packages those patterns as named, typed hooks so the same implementation is reused rather than rewritten per component.

The README states the hooks are built on DRY principles and that there are hooks for most common use cases. It also says most hooks are extensively tested and are being used in production environments. That wording matters: it is a claim about most hooks, not all of them, so the testing story is uneven across the list.

The intended audience is a TypeScript React developer working on the web. The library assumes a browser: hooks like useMediaQuery, useScreen, useScrollLock and useDarkMode wrap DOM APIs such as matchMedia and window.screen. If your target is React Native, the README has no native-specific hooks, and the RELATED SEARCHES phrase about React Native has no matching content in the documentation.

How the library is structured and what tree-shaking actually means here

The repository is a pnpm workspace driven by Turborepo. The root package.json is private and named workspace, with dev, build, test and lint scripts that all delegate to turbo run. Code lives under packages/ and apps/, the site is the Next.js app behind usehooks-ts.com, and the published package is the workspace package whose version appears in the release list ([email protected], published 2025-02-05).

Tree-shaking is the design claim worth understanding. The README says the library is fully tree-shakable using the ESM version, meaning you import the hooks you need and the rest are removed from your bundle. That only holds if your bundler resolves the ESM entry rather than a CommonJS build, and if you import from the package root rather than pulling in a barrel that defeats the analysis. The README does not document per-hook entry points, so the practical advice is to import named hooks and confirm the final bundle rather than assume.

The root package.json is also worth reading as a signal of process: Changesets drives versioning, a turbo generator (pnpm gen-hook, backed by turbo/generators/config.cts) scaffolds new hooks, and the build emits docs through typedoc. That is a maintained contributor workflow rather than a folder of loose files.

Installing usehooks-ts and using useLocalStorage in a component

The README gives the install command directly. It is a single npm package with no runtime peer setup described beyond React itself.

npm i usehooks-ts

After that, import the hooks you need by name. The README's own usage example uses useLocalStorage, which persists state across page reloads through the localStorage API.

import { useLocalStorage } from 'usehooks-ts'

function Component() {
  const [value, setValue] = useLocalStorage('my-localStorage-key', 0)

  // ...
}

The hook returns a tuple: the current value and a setter, matching the shape of useState. The first argument is the storage key and the second is the initial value used when nothing is stored yet. Because the value is read from localStorage, the first render on the server has no stored value to read, so the initial value is what you see before hydration. The README does not document a hydration strategy for this hook, so if your component renders differently based on stored state, that gap is yours to handle.

For a debounced input, useDebounceValue returns a debounced version of the provided value along with a function to update it, and useDebounceCallback creates a debounced version of a callback. Those two cover the common search-as-you-type case without extra dependencies.

Where usehooks-ts stops: no state layer, no native, uneven test coverage

The library is deliberately minimal, and the README says so. It is a set of hooks, not a state management system. useLocalStorage and useSessionStorage persist to browser storage, useMap manages a Map in component state, and useStep tracks a multi-step process. None of that coordinates across components or survives a route change unless the underlying browser API does. If you need shared state, caching or server synchronization, this library does not provide it and you will be pairing it with something else.

The second boundary is the browser. Hooks like useClickAnyWhere, useEventListener, useIntersectionObserver and useResizeObserver wrap DOM APIs. useIsomorphicLayoutEffect exists specifically to pick useLayoutEffect or useEffect depending on whether code runs on the client or the server, which tells you the authors expect server rendering. But that is a compatibility helper, not a port.

The third is coverage. The README claims most hooks are extensively tested, which is a hedged statement. Before depending on a less common hook, check its own documentation page rather than assuming the whole package carries the same test weight. The README does not publish a per-hook test matrix.

usehooks-ts compared with uidotdev/usehooks and with react-use

The search data around this project is largely comparative, and the comparison is fair because the alternatives differ in approach rather than in feature count.

uidotdev/usehooks is the closest match in spirit: a copy-paste-friendly collection of React hooks. The practical difference is distribution. usehooks-ts ships as an npm package you install and import, with a versioned release history and a Changesets workflow behind it. The copy-paste model gives you the source in your repository, which means you can edit a hook freely and you carry no upgrade obligation, but you also carry the maintenance of every hook you copy. Choosing between them is really choosing between a dependency and a fork.

react-use is the other common point of comparison in the search data, and it is broader. It covers a much wider surface, including hooks that touch browser APIs beyond what usehooks-ts lists. The trade-off is the same one that applies to any larger utility library: more surface to audit, and more code that may not match your TypeScript strictness. usehooks-ts keeps its list to the hooks enumerated in the README, which makes the audit smaller.

Maintenance cost, versioning and the MIT licence

The repository is not archived, and the last push was on 2026-09-21, so the project is being touched. That is not the same as a steady release cadence: the release list shows [email protected] on 2025-02-05, preceded by 3.1.0 on 2024-04-04 and 3.0.2 on 2024-03-22. Roughly a year separates the last two minor releases. If you pin a version, expect to sit on it for a while, and expect the changelog to be sparse rather than continuous.

The upgrade path is conventional for npm: the package.json declares engines.node >=18.17.0, and Changesets handles version bumps and publishing through the changeset, changeset-version and changeset-publish scripts. For consumers, that means semver releases with a changelog rather than a rolling master branch you are expected to track.

The licence is MIT, declared in the root package.json and shown as a badge in the README. MIT permits commercial use and modification with the licence and copyright notice retained. Whether that fits your organisation's policy on attribution in distributed bundles is a question for your legal team, not something this article can settle.

Editorial conclusion

Adopt usehooks-ts if you are building a React web app in TypeScript and want small, individually importable hooks instead of writing your own effect plumbing. Skip it if you need React Native support or a full state management layer, since the README lists no native-specific hooks and the library is explicitly minimal. Before adopting, verify which hooks you actually need against the published hook list, confirm that your build resolves the ESM entry point so tree-shaking works, and check whether the hook you depend on is described as extensively tested or not, because the README does not make that claim for every entry.

Frequently asked questions

Official sources

1. juliencrn/usehooks-ts on GitHub
2. License: MIT
3. Project website
4. README
5. Releases