useQueue

This hook controls the dispatcher queues. It uses the Dispatcher to read the actual value of the queue, which is based on the queryKey retrieved from the request passed as the first argument.

A prepared Request is the minimum requirement for useQueue.

Read the API Reference »

---

Purpose

1. Queue control for requests: Manage and observe the queue of requests for a given Request instance.
2. Fine-grained request lifecycle: Start, stop, and pause entire queues or individual requests.
3. Real-time updates: Reactively track the state of all requests in the queue.
4. Integration with Dispatcher: Leverages the Dispatcher for queue management and event updates.
5. Advanced queue strategies: Works best with one-by-one dispatching and the queued option enabled.

---

Quick Start

To use useQueue, provide a prepared Request instance. The hook returns the current queue state and control methods.

Controlling a request queue

import { useQueue } from "@hyper-fetch/react";
import { getUsers } from "./api/users";

function App() {
  const { requests } = useQueue(getUsers);

  return (
    <div>
      <ul>
        {/* List of currently running requests */}
        {requests.map((req) => (
          <li key={req.requestId}>{req.request.endpoint}</li>
        ))}
      </ul>
    </div>
  );
}

Request

Learn more about creating and configuring requests.

---

How it works

useQueue uses the request's queryKey to read and control the Dispatcher queue. It subscribes to Dispatcher events to keep the queue state up to date. This hook is ideal for advanced scenarios where you need to:

• Control the execution order of requests
• Pause, stop, or resume queued requests
• Monitor the status of all requests in a queue
• Integrate with custom queueing strategies

It works best with the one-by-one dispatching mode and when the queued option is set to true on the request.

caution

Remember to ensure your request's queryKey is static when using this hook. If your request uses dynamic params or query params, auto-generated keys may cause incorrect queue tracking. Provide a custom queryKey when creating the request to avoid this issue.

---

Controlling the Queue

The hook returns methods to control the queue and individual requests:

const { requests, stopped, stop, start, pause } = useQueue(getUsers);

// Control all requests in the queue
stop(); // Stops the queue
pause(); // Pauses the queue
start(); // Starts the queue

// Control individual requests
requests.forEach((req) => {
  req.stopRequest();
  req.startRequest();
  req.deleteRequest();
});

Per-request actions

Each request object in the requests array provides methods for fine-grained control:

Method	Description
stopRequest()	Stops the individual request from being dispatched.
startRequest()	Resumes the individual request so it can be dispatched.
deleteRequest()	Removes the request from the queue entirely.

Read more about the differences between stop, pause, and start in the Dispatcher documentation.

---

Options

Customize the behavior of useQueue by passing an options object as the second argument.

const { ... } = useQueue(request, options);

Key Options

Option	Default	Description
keepFinishedRequests	false	When true, completed requests remain in the requests list instead of being removed after they finish. Useful for displaying upload/download history or a log of completed operations.
dispatcherType	"auto"	Choose which dispatcher to monitor: "auto" picks the dispatcher based on the request's method, "fetch" monitors the fetch dispatcher, and "submit" monitors the submit dispatcher.

UseQueueOptionsType

Name	Type	Description
dispatcherType	auto | fetch | submit	Which dispatcher to use: "auto" picks based on request method, "fetch" or "submit" forces a specific one
keepFinishedRequests	boolean	When true, completed requests remain in the queue list for inspection

UseQueueOptionsType API Reference

Learn more about the useQueue hook options.

---

Returns

useQueue returns an object with the current queue state, control methods, and request helpers.

const values = useQueue(request);

useQueue

Name	Type	Description
dispatcher	Dispatcher<ExtractAdapterType<T>>	Request dispatcher instance
requests	QueueRequest<T>[]	List of requests for provided request
stopped	boolean	Queue status for provided request
pause	() => void	Callback which allow to pause queue. It will allow ongoing requests to be finished, but will stop next from being send.
start	() => void	Callback which allow to start queue.
stop	() => void	Callback which allow to stop queue, it will cancel ongoing requests.

useQueue API Reference

Learn more about the useQueue hook.

Request interface

QueueRequest

Name	Type	Description
request	Request
canceled	boolean	Whether the request was canceled before completing
downloading	ProgressType	Downloading progress for given request
failed	boolean	Whether the request has failed after all retry attempts
removed	boolean	Whether the request was removed from the queue
success	boolean	Whether the request completed successfully
uploading	ProgressType	Uploading progress for given request
deleteRequest	() => void	Removes request from the queue
startRequest	() => void	Callback which allow to start previously stopped request.
stopRequest	() => void	Callback which allow to stop request and cancel it if it's ongoing.

QueueRequest API Reference

Learn more about the QueueRequest type.

---

See More

Dispatcher

Learn more about the Dispatcher and queue management.

useFetch

Learn more about the useFetch hook.

useSubmit

Learn more about the useSubmit hook.