React

React Hyper Fetch is a data fetching library that implements the main features of the core library and adapts it to the React environment. It handles fetching, submitting, streaming, and queueing requests as well as their management in the system.

Together with the provided hooks, React Hyper Fetch makes maintaining and writing new functionalities faster and easier.

Note: A previously prepared request is the minimum requirement for using hooks.

React 18+ Required

This package requires React 18 or later. The hooks use useSyncExternalStore internally for correct concurrent mode semantics, selective re-rendering, and tearing prevention.

info

This package provides hooks for both: core and sockets subpackages.

---

Usage

To use hooks, we need to initialize the client and request instances that will be consumed as properties. Take a look at the Quick Start for more examples and check out our React code examples

const { data, error, loading } = useFetch(getUsers);

const { submit, data, error, submitting } = useSubmit(postLogin);

const { text, chunks, streaming, start, abort } = useStream(getStreamResponse);

Check our react code examples

---

Performance & Debugging

Selective Re-rendering

All hooks use field-level dependency tracking. If your component only reads data, it will not re-render when error or loading changes. This optimization happens automatically — just destructure the fields you need.

// This component only re-renders when `data` changes
const { data } = useFetch(getUsers);

Console-Friendly Output

Hook return values produce readable output in the browser console and Node.js console.log. You will see actual values like { data: {...}, error: null, loading: false } instead of opaque getter references. This works through a tracked proxy that snapshots the current state when inspected.

---

Provider

The <Provider> component sets global defaults for all hooks in the component tree. Wrap your application (or a subtree) with <Provider> to configure shared options once instead of repeating them on every hook call.

Setting global defaults

import { Provider } from "@hyper-fetch/react";

function App() {
  return (
    <Provider
      config={{
        useFetchConfig: {
          revalidate: true,
          refetchOnReconnect: true,
          refetchOnFocus: true,
          dependencyTracking: true,
        },
        useSubmitConfig: {
          bounce: true,
          bounceTime: 300,
        },
        useCacheConfig: {
          dependencyTracking: true,
        },
        useQueueConfig: {
          keepFinishedRequests: false,
        },
      }}
    >
      {/* All hooks inside this tree inherit the config above */}
      <Dashboard />
    </Provider>
  );
}

The config object supports these keys:

Key	Applies to	Description
useFetchConfig	useFetch	Default options for all useFetch hooks.
useSubmitConfig	useSubmit	Default options for all useSubmit hooks.
useCacheConfig	useCache	Default options for all useCache hooks.
useQueueConfig	useQueue	Default options for all useQueue hooks.

Options passed directly to a hook always override the Provider defaults.

---

Helper hooks

To break down our hook setups into smaller parts, we implemented helper hooks. This enhances code readability; the idea is that the main hook returns minor helpers, which lets us segregate our logic into smaller parts. It's quite simple, as you can see in the example below:

const {
  data,
  error,
  loading,
  onRequestStart,
  onResponseStart,
  onSuccess,
  onError,
  onDownloadProgress,
  onUploadProgress,
  onFinished,
  onAbort,
  onOfflineError,
} = useFetch(getUsers);

onRequestStart(({ details, request }) => {
  // Do something on query start
});

onResponseStart(({ response, details, request }) => {
  // Do something when query starts returning response
});

onSuccess(({ response, details, request }) => {
  // Do something on query success
});

onError(({ response, details, request }) => {
  // Do something on query fail
});

onAbort(({ response, details, request }) => {
  // Do something on query cancellation
});

onOfflineError(({ response, details, request }) => {
  // Do something when query goes stale while offline
});

onFinished(({ response, details, request }) => {
  // Do something on query finished (success or false)
});

onUploadProgress(({ progress, sizeLeft, timeLeft, total, loaded }) => {
  // Do something on upload
});

onDownloadProgress(({ progress, sizeLeft, timeLeft, total, loaded }) => {
  // Do something on download
});