v4.2.12

use-queue

Add data to queue if current limit is exceeded
Import
Source
View source code
Docs
Edit this page
Package
@mantine/hooks

Usage

use-queue limits the amount of data in current state and place 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 });
Go back
use-pagination – @mantine/hooks
Up next
use-set-state – @mantine/hooks
Build fully functional accessible web applications faster than ever
About
ContributeMedia assetsChangelogReleases
Community
Chat on DiscordFollow on TwitterFollow on GithubGitHub discussions
Project
Mantine UIDocumentationGithub organizationnpm organization
Built by Vitaly Rtishchev and these awesome people
Join Discord community
Follow Mantine on Twitter