alibaba/hooks (ahooks): A React Hooks Library for Data Fetching, State and DOM

What ahooks Is and Who Ends Up Using It

ahooks is a collection of React Hooks written in TypeScript, published to npm under the name ahooks and developed in the alibaba/hooks repository. The README describes it as "a high-quality & reliable React Hooks library" and lists its feature set as easy learning, SSR support, special treatment for functions to avoid closure problems, advanced Hooks refined from business scenarios, a comprehensive collection of basic Hooks, and static types.

The audience is narrower than the tagline suggests. This is not a state manager. It is a set of reusable behaviours that sit between React and whatever library you already chose for fetching, storage or layout measurement. A team that already runs axios and wants loading, cancellation and polling handled consistently across fifty components is the natural fit. So is a team that keeps rewriting the same debounce, interval and intersection-observer effects in every project.

The repository is a pnpm workspace. package.json declares "private": true at the root, so the root package is never published; the shipped artifacts come from the packages/ directory, and the build script is pnpm -r --filter=./packages/* run build. That layout matters when you want to read the source of a hook rather than the docs page.

The Mechanism: Hooks Grouped by Business Scenario

The design decision that separates ahooks from a grab bag of utility hooks is the README's phrase "advanced Hooks that are refined from business scenarios". The library is organised around recurring application problems rather than around primitives. useRequest is the clearest example: it wraps an asynchronous function and exposes the surrounding lifecycle, so the hook, not the component, owns the loading flag, the error, the cancellation path and the refresh trigger.

The second stated mechanism is "special treatment for functions, avoid closure problems". Stale closures are the classic failure of hand-written effects: a callback captures an old value and keeps calling it. ahooks addresses this at the library level, which is why its hooks accept a function where a plain React hook would accept a value. The README does not spell out the implementation, so treat this as a design promise rather than a documented algorithm.

The third mechanism is breadth. Alongside the advanced hooks there is what the README calls "a comprehensive collection of basic Hooks", covering state, effects and DOM observation. In practice you adopt one or two advanced hooks first, then discover the basic ones while reading the sidebar. TypeScript is not decoration here: the repository's primary language is TypeScript, and the README promises "predictable static types", which is what makes the function-versus-value distinction tolerable in an editor.

Installing ahooks and Importing Your First Hook

The README gives four package managers. Pick the one your lockfile already uses; mixing them is the fastest way to get two copies of React.

$ npm install --save ahooks
# or
$ yarn add ahooks
# or
$ pnpm add ahooks
# or
$ bun add ahooks

Importing is a named import from the package root. The README's usage example is exactly one line, reproduced here verbatim.

import { useRequest } from "ahooks";

That is the whole documented first step: install the package, then import the hook you need by name. The README does not print a full component example, so the next thing to do is read the documentation page for the specific hook you want rather than guessing at its return shape. For useRequest, the README's feature list says the library gives "special treatment for functions, avoid closure problems", which is the reason the hook takes a function rather than a value.

If you want to run the documentation site locally instead of consuming the published package, the contributing section of the README gives the workspace commands. They require pnpm and clone the repository before building it.

$ git clone [email protected]:alibaba/hooks.git
$ cd hooks
$ pnpm run init
$ pnpm start

The README states that the dev server is then reachable at http://127.0.0.1:8000.

The use-url-state Rename Is a Real Upgrade Trap

The README carries a notice that is easy to skim past: use-url-state is now published as @ahooks.js/use-url-state, and the notice tells anyone installing or upgrading to use the new package name. That means an import of use-url-state from the main ahooks package is not the path the project now points at.

This is the kind of split that produces confusing failures. A dependency bump that looks routine can leave a component importing a hook that the maintainers have moved out. If you have use-url-state anywhere in your codebase, search for it before you touch your lockfile, and read the notice on the README and the package page for @ahooks.js/use-url-state rather than assuming the old import still resolves.

The release history reinforces that upgrades deserve attention. v3.10.0 landed on 2026-09-06, v3.9.7 on 2026-03-23, and v3.9.6 on 2025-10-27. That is a normal cadence for a library of this size, but it also means a pinned version can sit several releases behind before anyone notices a moved package.

Where ahooks Is the Wrong Tool

ahooks is not a server-state cache. useRequest manages the lifecycle of one request inside one component tree. It does not give you a normalised store, cross-component deduplication of identical queries, background refetch on window focus, or garbage collection of unused cache entries. If your problem is "three components mount at once and each fires the same GET", ahooks will faithfully fire three requests. That is a different library's job, and reaching for ahooks to solve it leads to hand-rolled caching that the library never promised.

It is also not a router, not a global store, and not a form library. The README's feature list is explicit about scope: basic and advanced hooks, SSR support, types. Nothing in it claims routing or persistence.

The SSR claim deserves its own caution. The README lists SSR support as a feature, but SSR correctness depends on which hook you use and where. A DOM-observation hook or one that reads window during render behaves differently on the server than a pure state hook. The feature line tells you the library was built with SSR in mind; it does not tell you that every hook in the collection is safe in your particular render path. Test the specific hook you plan to use under your framework's server render before you build on it.

How It Differs from TanStack Query and SWR

The honest comparison is with TanStack Query or SWR, because both occupy the space ahooks deliberately does not. Those libraries treat the server cache as the primary object: a query key identifies a piece of remote state, components subscribe to it, and the cache decides when to refetch, deduplicate and expire. useRequest treats the request as an effect owned by the component that called it.

The practical difference shows up the moment two components need the same data. With a cache-first library, the second component reads what the first already fetched. With useRequest, you either lift the call to a shared parent or accept two requests. The trade-off runs the other way too: a cache-first library asks you to think in keys, invalidation and staleness, which is real overhead for a component that makes one call on mount and never again.

ahooks also covers ground neither of those libraries touches. Throttling, debouncing, DOM observation and the basic state and effect hooks live in the same import path. That is the argument for ahooks: one dependency for the behavioural layer, with the fetching hook included rather than bolted on. If your fetching needs are already complex, the cache-first libraries are the better centre of gravity and ahooks becomes an optional companion for the non-fetching hooks.

Maintenance, Licence and Upgrade Cost

The repository is not archived, and its last push was on 2026-09-21. The most recent release in the list is v3.10.0 from 2026-09-06, with the prior two releases in March 2026 and October 2025. Read that as a project that ships when there is something to ship rather than on a fixed train.

The licence is MIT, stated in the README badge and confirmed by the LICENSE file at the repository root. MIT is permissive: it allows commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is a statement about the licence text, not legal advice; if your organisation has a policy on third-party dependencies, route it through whoever owns that policy.

Upgrade cost is dominated by two things. First, the use-url-state move to @ahooks.js/use-url-state, which is a codemod-sized change but only if you find the imports. Second, the function-heavy API surface: because hooks accept callbacks where plain React hooks accept values, a major version that changes those signatures touches call sites rather than just the dependency line. The repository is a pnpm workspace with a strict preinstall guard (npx only-allow pnpm), so if you plan to contribute rather than consume, expect to work inside that toolchain.

Editorial conclusion

Adopt ahooks if your React app already fetches with axios or fetch and you want the surrounding lifecycle handled: loading flags, cancellation, polling, debounce and DOM observers. Do not adopt it as a replacement for a server-state cache such as TanStack Query, and do not expect it to cover routing or global stores. Before committing, verify the use-url-state package rename, confirm your React version against the peer range in the published package.json, and check that the specific hook you need is exported from the installed version rather than only from the docs site.

Frequently asked questions

Official sources

1. alibaba/hooks on GitHub
2. License: MIT
3. Project website
4. README
5. Releases