From e5d125df16c306f90980a4a336d17444d1232697 Mon Sep 17 00:00:00 2001
From: Mohit Jain <jainmohit535@gmail.com>
Date: Sat, 1 Aug 2026 16:30:46 +0530
Subject: [PATCH 1/2] feat: added prepend prop for priority toast

---
 playground/src/components/App.tsx | 33 ++++++++++++++++++-
 src/core/containerObserver.ts     | 20 ++++++++++--
 src/core/toast.cy.tsx             | 54 +++++++++++++++++++++++++++++++
 src/types.ts                      |  7 ++++
 4 files changed, 110 insertions(+), 4 deletions(-)

diff --git a/playground/src/components/App.tsx b/playground/src/components/App.tsx
index acde3d51..b2c8141c 100644
--- a/playground/src/components/App.tsx
+++ b/playground/src/components/App.tsx
@@ -30,7 +30,7 @@ class App extends React.Component {
       ...defaultProps,
       transition: 'bounce',
       type: 'default',
-      progress: '',
+      progress: 0,
       disableAutoClose: false,
       limit: 0,
       theme: 'light'
@@ -71,6 +71,22 @@ class App extends React.Component {
 
   updateToast = () => toast.update(this.toastId, { progress: this.state.progress });
 
+  showPriorityToast = () => {
+    toast('🥇 Priority toast! (prepend: true)', { prepend: true });
+  };
+
+  firePrependQueueDemo = () => {
+    toast.dismiss({ containerId: 'prepend-demo' });
+    toast.clearWaitingQueue({ containerId: 'prepend-demo' });
+    toast('Queued 1', { containerId: 'prepend-demo' });
+    toast('Queued 2', { containerId: 'prepend-demo' });
+    toast('Queued 3', { containerId: 'prepend-demo' });
+    toast('🥇 Priority toast, skips the queue!', {
+      containerId: 'prepend-demo',
+      prepend: true
+    });
+  };
+
   handleAutoCloseDelay = e =>
     this.setState({
       autoClose: e.target.value > 0 ? parseInt(e.target.value, 10) : 1
@@ -219,6 +235,14 @@ class App extends React.Component {
                   Show Toast
                 </button>
               </li>
+              <li>
+                <button className="btn" onClick={this.showPriorityToast}>
+                  <span role="img" aria-label="show priority alert">
+                    🥇
+                  </span>{' '}
+                  Priority Toast (prepend)
+                </button>
+              </li>
               <li>
                 <button className="btn" onClick={this.firePromise}>
                   Promise
@@ -255,6 +279,13 @@ class App extends React.Component {
         />
         <ToastContainer containerId="xxx" position="top-left" autoClose={false} theme="dark" limit={3} />
         <ToastContainer limit={3} containerId="yyy" autoClose={false} position="top-right" />
+        <ToastContainer
+          containerId="prepend-demo"
+          limit={1}
+          autoClose={false}
+          position="bottom-center"
+          theme="colored"
+        />
       </main>
     );
   }
diff --git a/src/core/containerObserver.ts b/src/core/containerObserver.ts
index 31dd3219..aa00b21a 100644
--- a/src/core/containerObserver.ts
+++ b/src/core/containerObserver.ts
@@ -74,13 +74,23 @@ export function createContainerObserver(
   };
 
   const addActiveToast = (toast: Toast) => {
-    const { toastId, updateId } = toast.props;
+    const { toastId, updateId, prepend } = toast.props;
     const isNew = updateId == null;
 
     if (toast.staleId) toasts.delete(toast.staleId);
     toast.isActive = true;
 
-    toasts.set(toastId, toast);
+    if (isNew && prepend && toasts.size > 0) {
+      // `Map` preserves insertion order, so to bring this toast to the front we
+      // need to rebuild it with the new entry first, followed by the rest untouched.
+      const entries = Array.from(toasts.entries()).filter(([id]) => id !== toastId);
+      toasts.clear();
+      toasts.set(toastId, toast);
+      entries.forEach(([id, t]) => toasts.set(id, t));
+    } else {
+      toasts.set(toastId, toast);
+    }
+
     notify();
     dispatchChanges(toToastItem(toast, isNew ? 'added' : 'updated'));
 
@@ -151,7 +161,11 @@ export function createContainerObserver(
 
     // not handling limit + delay by design. Waiting for user feedback first
     if (props.limit && props.limit > 0 && toastCount > props.limit && isNotAnUpdate) {
-      queue.push(activeToast);
+      if (options.prepend) {
+        queue.unshift(activeToast);
+      } else {
+        queue.push(activeToast);
+      }
     } else if (isNum(delay)) {
       setTimeout(() => {
         addActiveToast(activeToast);
diff --git a/src/core/toast.cy.tsx b/src/core/toast.cy.tsx
index ebea85d9..7346224a 100644
--- a/src/core/toast.cy.tsx
+++ b/src/core/toast.cy.tsx
@@ -457,6 +457,60 @@ describe('with container', () => {
   });
 });
 
+describe('with prepend option', () => {
+  beforeEach(() => {
+    cy.mount(<ToastContainer autoClose={false} closeOnClick />);
+  });
+
+  it('inserts the toast before the ones already displayed', () => {
+    toast('msg1');
+    toast('msg2');
+    cy.resolveEntranceAnimation();
+
+    toast('msg3', { prepend: true });
+    cy.resolveEntranceAnimation();
+
+    cy.findAllByRole('alert').should('have.length', 3);
+    cy.findAllByRole('alert').eq(0).should('have.text', 'msg3');
+    cy.findAllByRole('alert').eq(1).should('have.text', 'msg1');
+    cy.findAllByRole('alert').eq(2).should('have.text', 'msg2');
+  });
+
+  it('does not affect the order when there is nothing displayed yet', () => {
+    toast('msg1', { prepend: true });
+    cy.resolveEntranceAnimation();
+
+    cy.findAllByRole('alert').should('have.length', 1);
+    cy.findAllByRole('alert').eq(0).should('have.text', 'msg1');
+  });
+});
+
+describe('with limit and prepend option', () => {
+  it('prepended toast becomes the next one to appear when the limit is reached', () => {
+    cy.mount(<ToastContainer autoClose={false} limit={2} closeOnClick />);
+
+    toast('msg1');
+    toast('msg2');
+    toast('msg3');
+    toast('msg4', { prepend: true });
+    cy.resolveEntranceAnimation();
+
+    cy.findByText('msg1').should('exist');
+    cy.findByText('msg2').should('exist');
+    cy.findByText('msg3').should('not.exist');
+    cy.findByText('msg4').should('not.exist');
+
+    cy.findByText('msg1')
+      .click()
+      .then(() => {
+        cy.resolveEntranceAnimation();
+
+        cy.findByText('msg4').should('exist');
+        cy.findByText('msg3').should('not.exist');
+      });
+  });
+});
+
 describe.skip('with multi containers', () => {
   const Containers = {
     First: 'first',
diff --git a/src/types.ts b/src/types.ts
index e363ce19..59cd393d 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -221,6 +221,13 @@ export interface ToastOptions<Data = unknown> extends CommonOptions {
   delay?: number;
 
   isLoading?: boolean;
+
+  /**
+   * Insert the toast before any other toast currently displayed or waiting in the queue,
+   * instead of appending it after them.
+   * `Default: false`
+   */
+  prepend?: boolean;
 }
 
 export interface UpdateOptions<T = unknown> extends Nullable<ToastOptions<T>> {

From cb71d3c20b5b8f15b80890ed83355b8c3c1540f8 Mon Sep 17 00:00:00 2001
From: Mohit Jain <jainmohit535@gmail.com>
Date: Sat, 1 Aug 2026 16:31:24 +0530
Subject: [PATCH 2/2] chor: removed unwanted

---
 playground/src/components/App.tsx | 19 -------------------
 1 file changed, 19 deletions(-)

diff --git a/playground/src/components/App.tsx b/playground/src/components/App.tsx
index b2c8141c..bc608962 100644
--- a/playground/src/components/App.tsx
+++ b/playground/src/components/App.tsx
@@ -75,18 +75,6 @@ class App extends React.Component {
     toast('🥇 Priority toast! (prepend: true)', { prepend: true });
   };
 
-  firePrependQueueDemo = () => {
-    toast.dismiss({ containerId: 'prepend-demo' });
-    toast.clearWaitingQueue({ containerId: 'prepend-demo' });
-    toast('Queued 1', { containerId: 'prepend-demo' });
-    toast('Queued 2', { containerId: 'prepend-demo' });
-    toast('Queued 3', { containerId: 'prepend-demo' });
-    toast('🥇 Priority toast, skips the queue!', {
-      containerId: 'prepend-demo',
-      prepend: true
-    });
-  };
-
   handleAutoCloseDelay = e =>
     this.setState({
       autoClose: e.target.value > 0 ? parseInt(e.target.value, 10) : 1
@@ -279,13 +267,6 @@ class App extends React.Component {
         />
         <ToastContainer containerId="xxx" position="top-left" autoClose={false} theme="dark" limit={3} />
         <ToastContainer limit={3} containerId="yyy" autoClose={false} position="top-right" />
-        <ToastContainer
-          containerId="prepend-demo"
-          limit={1}
-          autoClose={false}
-          position="bottom-center"
-          theme="colored"
-        />
       </main>
     );
   }