feat: deduplication toasts with nice animation

Author: y0u-0

README.md

@@ -140,6 +140,7 @@ toast.success('Saved!', {
   style: { backgroundColor: '#fff' },
   dismissible: true,
   showCloseButton: true,
+  deduplication: true, // Prevents duplicate toasts, resets timer instead
 });
 ```
 
@@ -201,10 +202,41 @@ Available options include:
 - **dismissible**: Allow swipe to dismiss
 - **showCloseButton**: Show X button
 - **defaultDuration**: Default display time in ms
+- **deduplication**: Prevent duplicate toasts (see below)
 - **colors**: Custom colors per toast type
 - **icons**: Custom icons per toast type
 - **toastStyle**, **titleStyle**, **descriptionStyle**: Global style overrides
 
+### Deduplication
+
+When the same toast is shown repeatedly (e.g., rapid button taps), deduplication prevents stacking identical toasts. Instead, it resets the timer and plays a feedback animation:
+
+- **Non-error toasts**: subtle pulse (scale bump)
+- **Error toasts**: shake effect
+
+Enable globally:
+
+```tsx
+<BreadLoaf config={{ deduplication: true }} />
+```
+
+Or per-toast (overrides global config):
+
+```tsx
+toast.success('Liked!', { deduplication: true });
+toast.error('Rate limited', { deduplication: true });
+
+// Opt out for a specific toast even when global is on
+toast.info('New message', { deduplication: false });
+```
+
+By default, a toast is considered a duplicate when it matches the **front toast** by title, type, and description. For stable matching across different content, provide an `id` — the existing toast's content will be updated:
+
+```tsx
+toast.success('Saved item 1', { deduplication: true, id: 'save-action' });
+toast.success('Saved item 2', { deduplication: true, id: 'save-action' }); // updates content, resets timer
+```
+
 ## API Reference
 
 | Method | Description |

example/react-native-bread-example/app/(custom)/index.tsx

@@ -112,6 +112,30 @@ export default function CustomScreen() {
             <Text style={styles.buttonText}>No Close Button</Text>
           </TouchableOpacity>
 
+          <TouchableOpacity
+            style={[styles.button, { backgroundColor: "#f59e0b" }]}
+            onPress={() =>
+              toast.success("Liked!", {
+                description: "Tap again — it won't stack",
+                deduplication: true,
+              })
+            }
+          >
+            <Text style={styles.buttonText}>Deduplication (Pulse)</Text>
+          </TouchableOpacity>
+
+          <TouchableOpacity
+            style={[styles.button, { backgroundColor: "#dc2626" }]}
+            onPress={() =>
+              toast.error("Rate limited", {
+                description: "Please wait before retrying",
+                deduplication: true,
+              })
+            }
+          >
+            <Text style={styles.buttonText}>Deduplication (Shake)</Text>
+          </TouchableOpacity>
+
           <TouchableOpacity
             style={[styles.button, { backgroundColor: "#8b5cf6" }]}
             onPress={() =>

example/react-native-bread-example/app/(global)/index.tsx

@@ -15,6 +15,7 @@ export default function GlobalConfigScreen() {
   const [showCloseButton, setShowCloseButton] = useState(true);
   const [customStyle, setCustomStyle] = useState(true);
   const [rtl, setRtl] = useState(false);
+  const [deduplication, setDeduplication] = useState(true);
 
   const showToast = () => {
     toast.success("Hello!", "This toast uses the global config");
@@ -38,6 +39,7 @@ export default function GlobalConfigScreen() {
           rtl,
           offset: 8,
           defaultDuration: 4000,
+          deduplication,
           ...(customStyle && {
             toastStyle: {
               borderRadius: 30,
@@ -146,6 +148,14 @@ export default function GlobalConfigScreen() {
             <Switch value={rtl} onValueChange={setRtl} />
           </View>
 
+          <View style={styles.option}>
+            <View>
+              <Text style={styles.optionLabel}>Deduplication</Text>
+              <Text style={styles.optionDesc}>Pulse/shake on repeated toasts</Text>
+            </View>
+            <Switch value={deduplication} onValueChange={setDeduplication} />
+          </View>
+
           <View style={styles.option}>
             <View>
               <Text style={styles.optionLabel}>Custom Styling</Text>

packages/react-native-bread/src/constants.ts

@@ -20,4 +20,7 @@ export const DISMISS_VELOCITY_THRESHOLD = 300;
 export const STACK_OFFSET_PER_ITEM = 10;
 export const STACK_SCALE_PER_ITEM = 0.05;
 
+export const DEDUPLICATION_PULSE_DURATION = 300;
+export const DEDUPLICATION_SHAKE_DURATION = 400;
+
 export const EASING = Easing.bezier(0.25, 0.1, 0.25, 1.0);

packages/react-native-bread/src/pool.ts

@@ -5,6 +5,7 @@ export interface AnimSlot {
   progress: SharedValue<number>;
   translationY: SharedValue<number>;
   stackIndex: SharedValue<number>;
+  deduplication: SharedValue<number>;
 }
 
 export interface SlotTracker {
@@ -17,6 +18,7 @@ export const animationPool: AnimSlot[] = Array.from({ length: POOL_SIZE }, () =>
   progress: makeMutable(0),
   translationY: makeMutable(0),
   stackIndex: makeMutable(0),
+  deduplication: makeMutable(0),
 }));
 
 export const slotTrackers: SlotTracker[] = Array.from({ length: POOL_SIZE }, () => ({

packages/react-native-bread/src/toast-provider.tsx

@@ -21,9 +21,15 @@ interface BreadLoafProps {
    *
    * @property position - Where toasts appear: `'top'` (default) or `'bottom'`
    * @property offset - Extra spacing from screen edge in pixels (default: `0`)
+   * @property rtl - Enable right-to-left layout (default: `false`)
    * @property stacking - Show multiple toasts stacked (default: `true`). When `false`, only one toast shows at a time
+   * @property maxStack - Maximum visible toasts when stacking (default: `3`)
+   * @property dismissible - Whether toasts can be swiped to dismiss (default: `true`)
+   * @property showCloseButton - Show close button on toasts (default: `true`)
    * @property defaultDuration - Default display time in ms (default: `4000`)
+   * @property deduplication - Deduplicate repeated toasts, resetting timer with pulse/shake animation (default: `false`)
    * @property colors - Customize colors per toast type (`success`, `error`, `info`, `loading`)
+   * @property icons - Custom icons per toast type
    * @property toastStyle - Style overrides for the toast container (borderRadius, shadow, padding, etc.)
    * @property titleStyle - Style overrides for the title text
    * @property descriptionStyle - Style overrides for the description text

packages/react-native-bread/src/toast-store.ts

@@ -23,6 +23,7 @@ const DEFAULT_THEME: ToastTheme = {
   titleStyle: {},
   descriptionStyle: {},
   defaultDuration: 4000,
+  deduplication: false,
 };
 
 function mergeConfig(config: ToastConfig | undefined): ToastTheme {
@@ -55,6 +56,7 @@ function mergeConfig(config: ToastConfig | undefined): ToastTheme {
     titleStyle: { ...DEFAULT_THEME.titleStyle, ...config.titleStyle },
     descriptionStyle: { ...DEFAULT_THEME.descriptionStyle, ...config.descriptionStyle },
     defaultDuration: config.defaultDuration ?? DEFAULT_THEME.defaultDuration,
+    deduplication: config.deduplication ?? DEFAULT_THEME.deduplication,
   };
 }
 
@@ -104,12 +106,34 @@ class ToastStore {
   ): string => {
     const actualDuration = duration ?? options?.duration ?? this.theme.defaultDuration;
     const maxToasts = this.theme.stacking ? this.theme.maxStack : 1;
+    const resolvedDescription = description ?? options?.description;
+
+    const shouldDedup = type !== "loading" && (options?.deduplication ?? this.theme.deduplication);
+    if (shouldDedup) {
+      const deduplicationId = options?.id;
+      const duplicate = deduplicationId
+        ? this.state.visibleToasts.find(t => !t.isExiting && t.options?.id === deduplicationId)
+        : this.state.visibleToasts.find(
+            t => !t.isExiting && t.title === title && t.type === type && t.description === resolvedDescription
+          );
+
+      if (duplicate) {
+        this.updateToast(duplicate.id, {
+          title,
+          description: resolvedDescription,
+          type,
+          deduplicatedAt: Date.now(),
+          duration: actualDuration,
+        });
+        return duplicate.id;
+      }
+    }
 
     const id = `toast-${++this.toastIdCounter}`;
     const newToast: Toast = {
       id,
       title,
-      description: description ?? options?.description,
+      description: resolvedDescription,
       type,
       duration: actualDuration,
       createdAt: Date.now(),

packages/react-native-bread/src/toast.tsx

@@ -1,10 +1,18 @@
-import { memo, useCallback, useEffect, useMemo, useState } from "react";
+import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { Pressable, StyleSheet, Text, View } from "react-native";
 import { Gesture, GestureDetector } from "react-native-gesture-handler";
-import Animated, { interpolate, useAnimatedStyle, useSharedValue, withTiming } from "react-native-reanimated";
+import Animated, {
+  interpolate,
+  useAnimatedStyle,
+  useSharedValue,
+  withSequence,
+  withTiming,
+} from "react-native-reanimated";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
 import { scheduleOnRN } from "react-native-worklets";
 import {
+  DEDUPLICATION_PULSE_DURATION,
+  DEDUPLICATION_SHAKE_DURATION,
   DISMISS_THRESHOLD,
   DISMISS_VELOCITY_THRESHOLD,
   EASING,
@@ -135,12 +143,14 @@ const ToastItem = ({ toast, index, theme, position, isTopToast, registerTopToast
 
   const [wasLoading, setWasLoading] = useState(toast.type === "loading");
   const [showIcon, setShowIcon] = useState(false);
+  const lastDeduplicatedAt = useRef(toast.deduplicatedAt);
 
   // biome-ignore lint/correctness/useExhaustiveDependencies: mount-only effect
   useEffect(() => {
     slot.progress.value = 0;
     slot.translationY.value = 0;
     slot.stackIndex.value = index;
+    slot.deduplication.value = 0;
     slot.progress.value = withTiming(1, { duration: ENTRY_DURATION, easing: EASING });
 
     const iconTimeout = setTimeout(() => setShowIcon(true), 50);
@@ -197,7 +207,34 @@ const ToastItem = ({ toast, index, theme, position, isTopToast, registerTopToast
     dismissToast,
   ]);
 
+  useEffect(() => {
+    if (toast.deduplicatedAt && toast.deduplicatedAt !== lastDeduplicatedAt.current) {
+      lastDeduplicatedAt.current = toast.deduplicatedAt;
+
+      if (toast.type === "error") {
+        const step = DEDUPLICATION_SHAKE_DURATION / 8;
+        slot.deduplication.value = 0;
+        slot.deduplication.value = withSequence(
+          withTiming(6, { duration: step }),
+          withTiming(-5, { duration: step }),
+          withTiming(4, { duration: step }),
+          withTiming(-3, { duration: step }),
+          withTiming(2, { duration: step }),
+          withTiming(-1, { duration: step }),
+          withTiming(0, { duration: step * 2 })
+        );
+      } else {
+        slot.deduplication.value = 0;
+        slot.deduplication.value = withSequence(
+          withTiming(1, { duration: DEDUPLICATION_PULSE_DURATION / 2, easing: EASING }),
+          withTiming(0, { duration: DEDUPLICATION_PULSE_DURATION / 2, easing: EASING })
+        );
+      }
+    }
+  }, [toast.deduplicatedAt, toast.type, slot]);
+
   const shouldAnimateIcon = wasLoading && toast.type !== "loading";
+  const isErrorType = toast.type === "error";
 
   const animatedStyle = useAnimatedStyle(() => {
     const baseTranslateY = interpolate(slot.progress.value, [0, 1], [entryFromY, 0]);
@@ -213,11 +250,14 @@ const ToastItem = ({ toast, index, theme, position, isTopToast, registerTopToast
     const dragOpacity = dismissDirection > 0 ? interpolate(dismissDirection, [0, 130], [1, 0], "clamp") : 1;
     const opacity = progressOpacity * dragOpacity;
 
+    const dedupVal = slot.deduplication.value;
     const dragScale = interpolate(Math.abs(slot.translationY.value), [0, 50], [1, 0.98], "clamp");
-    const scale = stackScale * dragScale;
+    const pulseScale = isErrorType ? 1 : 1 + dedupVal * 0.03;
+    const scale = stackScale * dragScale * pulseScale;
+    const shakeTranslateX = isErrorType ? dedupVal : 0;
 
     return {
-      transform: [{ translateY: finalTranslateY }, { scale }],
+      transform: [{ translateY: finalTranslateY }, { translateX: shakeTranslateX }, { scale }],
       opacity,
       zIndex: 1000 - Math.round(slot.stackIndex.value),
     };
@@ -325,6 +365,7 @@ const MemoizedToastItem = memo(ToastItem, (prev, next) => {
     prev.toast.title === next.toast.title &&
     prev.toast.description === next.toast.description &&
     prev.toast.isExiting === next.toast.isExiting &&
+    prev.toast.deduplicatedAt === next.toast.deduplicatedAt &&
     prev.index === next.index &&
     prev.position === next.position &&
     prev.theme === next.theme &&

packages/react-native-bread/src/types.ts

@@ -65,10 +65,14 @@ export interface ToastTheme {
   descriptionStyle: TextStyle;
   /** Default duration in ms for toasts (default: 4000) */
   defaultDuration: number;
+  /** When true, duplicate toasts reset the timer and play a feedback animation instead of stacking. Matches by title+type+description, or by `id` if provided. (default: false) */
+  deduplication: boolean;
 }
 
 /** Per-toast options for customizing individual toasts */
 export interface ToastOptions {
+  /** Stable key for deduplication. When set, toasts with the same `id` deduplicate and update the existing toast's content. Without an `id`, matching falls back to title+type+description against the front toast. */
+  id?: string;
   /** Description text */
   description?: string;
   /** Duration in ms (overrides default) */
@@ -91,6 +95,8 @@ export interface ToastOptions {
    * Receives props: { id, dismiss, type, isExiting }
    */
   customContent?: ReactNode | CustomContentRenderFn;
+  /** Enable deduplication for this toast (overrides global config). Plays a pulse animation for non-error toasts or a shake for errors. Use with `id` for stable matching across different content. */
+  deduplication?: boolean;
 }
 
 /** Configuration options for customizing toast behavior and appearance. All properties are optional. */
@@ -110,6 +116,7 @@ export interface Toast {
   duration: number;
   createdAt: number;
   isExiting?: boolean;
+  deduplicatedAt?: number;
   /** Per-toast style/icon overrides */
   options?: ToastOptions;
 }