StateBeginnerFully SSR-safehooks/state/useQueue.ts

useQueue

FIFO queue with enqueue/dequeue.

Import

TypeScript
import { useQueue } from '@/hooks';

API

Signature

useQueue<T>(initial?) → { queue, size, first, last, actions }

When to use

Use useQueue instead of re-implementing the same pattern in multiple components.

SSR / Next.js

Fully SSR-safe. Pure React state.

Live playground

Edit the example and see it run against the real @/hooks package in this app.

Live playgroundEdit · run with real @/hooks · useQueue
Editor
function Jobs() {
  const { queue, first, actions } = useQueue<string>(['job-1']);
  return (
    <div>
      <p>Front: {first}</p>
      <button onClick={() => actions.enqueue('job-' + (queue.length + 1))}>Enqueue</button>
      <button onClick={() => actions.dequeue()}>Dequeue</button>
    </div>
  );
}
Preview

Implementation source

Full library source for useQueue — copy into your project when you are not installing a package yet.

hooks/state/useQueue.ts
import { useCallback, useMemo, useState } from 'react';

export interface UseQueueActions<T> {
  enqueue: (item: T) => void;
  dequeue: () => T | undefined;
  peek: () => T | undefined;
  clear: () => void;
  reset: () => void;
}

export interface UseQueueReturn<T> {
  queue: T[];
  size: number;
  first: T | undefined;
  last: T | undefined;
  actions: UseQueueActions<T>;
}

/** FIFO queue state. */
export function useQueue<T>(
  initialValue: T[] = [],
): UseQueueReturn<T> {
  const [queue, setQueue] = useState<T[]>(initialValue);

  const enqueue = useCallback((item: T) => {
    setQueue((prev) => [...prev, item]);
  }, []);

  const dequeue = useCallback(() => {
    let removed: T | undefined;
    setQueue((prev) => {
      if (prev.length === 0) return prev;
      const [first, ...rest] = prev;
      removed = first;
      return rest;
    });
    return removed;
  }, []);

  const peek = useCallback(() => queue[0], [queue]);
  const clear = useCallback(() => setQueue([]), []);
  const reset = useCallback(() => setQueue(initialValue), [initialValue]);

  return {
    queue,
    size: queue.length,
    first: queue[0],
    last: queue[queue.length - 1],
    actions: useMemo(
      () => ({ enqueue, dequeue, peek, clear, reset }),
      [enqueue, dequeue, peek, clear, reset],
    ),
  };
}

Copy-paste example

useQueue.example.tsx
'use client';

import { useQueue } from '@/hooks';

export function Jobs() {
  const { queue, first, actions } = useQueue<string>(['job-1']);
  return (
    <div>
      <p>Front: {first}</p>
      <button onClick={() => actions.enqueue('job-' + (queue.length + 1))}>Enqueue</button>
      <button onClick={() => actions.dequeue()}>Dequeue</button>
    </div>
  );
}

Production checklist

  • Called only from Client Components or other custom hooks
  • Type parameters filled in (e.g. useFetch<User[]>)
  • Tip: Keep state setters stable; prefer action helpers over manual setState spreads.
  • Source of truth: open hooks/state/useQueue.ts for implementation details