use-queue

Add data to queue if current limit is exceeded
Import

Usage

use-queue limits the amount of data in current state and places the rest of it in a queue. For example, in @mantine/notifications package amount of notifications that is currently displayed is limited and other new notifications are added to queue and displayed once available space appears.

import { useQueue } from '@mantine/hooks';
const { state, queue, add, update, cleanQueue } = useQueue({
initialValues: [1],
limit: 2,
});
// state -> [1], queue -> []
// When state.length is less that limit, new items are added to state
add(2);
// state -> [1,2], queue -> []
// When state.length is equal to limit, new items are added to queue
add(3, 4, 5, 6);
// state -> [1,2], queue -> [3,4,5,6]
// Use update function to modify items
update((values) => values.map((item) => item * 3));
// state -> [3,6], queue -> [9,12,15,18]
// If you add or remove items in update function,
// they will be divided between queue and state according to limit
// order is always preserved
update((values) => values.filter((item) => item % 2));
// state -> [3,9], queue -> [15]
// Remove all items from queue
cleanQueue();
// state -> [3,9], queue -> []
// Remove all items from queue and state
update(() => []);
// state -> [], queue -> []

API

Hook accepts single argument – configuration object with keys:

  • initialValues – optional initial values (divided between state and queue according to limit), defaults to empty array
  • limit – maximum amount of items that state can include, every next item after limit is exceeded is put in queue

Return value:

  • state – current state
  • queue – current queue
  • add – add any amount of items to state or queue
  • update – apply given function to all items in state and queue, use it to filter, modify or add items
  • cleanQueue – remove all items from queue

Example

Example of use-queue hook usage in Mantine notifications system. By default only 5 notifications can be displayed at a time, rest are added to queue.

TypeScript

By default, hook will get types information from initialValues automatically:

const q = useQueue({
limit: 2,
initialValues: [
{ name: 'Bob', id: 1 },
{ name: 'Alice', id: 2 },
],
});
typeof q.state[number]; // -> { name: string; id: number; }

If you do not provide initialValues, pass in type for state item:

const q = useQueue<{ name: string; id: number }>({
limit: 2,
initialValues: [],
});
q.add({ name: 'Bob', id: 1 });

TypeScript

Definition

function useQueue<T>(configuration: { initialValues?: T[]; limit: number }): {
state: T[];
queue: T[];
add: (...items: T[]) => void;
update: (fn: (state: T[]) => T[]) => void;
cleanQueue: () => void;
};

Item type

Item type is set automatically based on initialValues, if you do not have initialValue it is required to pass in item type:

// ok -> typeof state[number] -> string
const { state } = useQueue({ initialValues: ['1', '2', '3'], limit: 3 });
// type cannot be assigned automatically, specify it
const { state } = useQueue<string>({ limit: 3 });