feat(toast): add maxVisibleToasts prop

Author: vvv-sss

src/components/toast/toast.animation.ts

@@ -1,4 +1,4 @@
-import { useWindowDimensions, type ViewStyle } from 'react-native';
+import { useWindowDimensions } from 'react-native';
 import { Gesture } from 'react-native-gesture-handler';
 import {
   Easing,
@@ -12,7 +12,6 @@ import {
   withDecay,
   withSpring,
   withTiming,
-  type SharedValue,
 } from 'react-native-reanimated';
 import { scheduleOnRN } from 'react-native-worklets';
 import {
@@ -22,7 +21,7 @@ import {
   getStyleProperties,
   getStyleTransform,
 } from '../../helpers/utils/animation';
-import type { ToastPlacement, ToastRootAnimation } from './toast.types';
+import type { UseToastRootAnimationOptions } from './toast.types';
 
 // --------------------------------------------------
 
@@ -71,17 +70,7 @@ export const exitingBottom = new Keyframe({
  * Handles opacity, translateY, and scale animations based on toast index and placement
  * Also handles gesture-based swipe to dismiss and rubber-band drag effects
  */
-export function useToastRootAnimation(options: {
-  animation: ToastRootAnimation | undefined;
-  style: ViewStyle | undefined;
-  index: number;
-  total: SharedValue<number>;
-  heights: SharedValue<Record<string, number>>;
-  placement: ToastPlacement;
-  hide?: ((ids?: string | string[]) => void) | undefined;
-  id?: string | undefined;
-  isSwipable?: boolean;
-}) {
+export function useToastRootAnimation(options: UseToastRootAnimationOptions) {
   const {
     animation,
     style,
@@ -92,6 +81,7 @@ export function useToastRootAnimation(options: {
     hide,
     id,
     isSwipable = true,
+    maxVisibleToasts = 3,
   } = options;
 
   const { height: screenHeight } = useWindowDimensions();
@@ -240,7 +230,7 @@ export function useToastRootAnimation(options: {
 
       if (placement === 'top') {
         // Top placement: dismiss if swiped up (negative Y)
-        if (shouldDismiss && translationY < 0 && id && hide) {
+        if (shouldDismiss && translationY < 0 && id) {
           // Use withDecay to continue motion with velocity
           gestureTranslateY.set(
             withDecay(
@@ -265,7 +255,7 @@ export function useToastRootAnimation(options: {
         }
       } else {
         // Bottom placement: dismiss if swiped down (positive Y)
-        if (shouldDismiss && translationY > 0 && id && hide) {
+        if (shouldDismiss && translationY > 0 && id) {
           // Use withDecay to continue motion with velocity
           gestureTranslateY.set(
             withDecay(
@@ -304,7 +294,10 @@ export function useToastRootAnimation(options: {
     const totalValue = total.get();
 
     const inputRange = [totalValue - 1, totalValue - 2];
-    const opacityInputRange = [totalValue - 3, totalValue - 4];
+    const opacityInputRange = [
+      totalValue - maxVisibleToasts,
+      totalValue - maxVisibleToasts - 1,
+    ];
 
     const opacity = interpolate(index, opacityInputRange, opacityValue);
     const scale = interpolate(index, inputRange, scaleValue);

src/components/toast/toast.tsx

@@ -40,6 +40,7 @@ const ToastRoot = forwardRef<ViewRef, ToastRootProps>((props, ref) => {
     index,
     total,
     heights,
+    maxVisibleToasts,
     className,
     style,
     animation,
@@ -70,6 +71,7 @@ const ToastRoot = forwardRef<ViewRef, ToastRootProps>((props, ref) => {
       hide,
       id,
       isSwipable,
+      maxVisibleToasts,
     });
 
   const contextValue = useMemo(

src/components/toast/toast.types.ts

@@ -1,3 +1,4 @@
+import type { ViewStyle } from 'react-native';
 import type {
   EntryOrExitLayoutType,
   WithTimingConfig,
@@ -205,3 +206,22 @@ export interface ToastContextValue {
  * Ref type for the Toast.Root component
  */
 export type ToastRootRef = ViewRef;
+
+/**
+ * Props for useToastRootAnimation hook
+ * Picks required properties from ToastRootProps and adds id from ToastComponentProps
+ */
+export type UseToastRootAnimationOptions = Pick<
+  ToastRootProps,
+  | 'animation'
+  | 'index'
+  | 'total'
+  | 'heights'
+  | 'placement'
+  | 'hide'
+  | 'isSwipable'
+  | 'maxVisibleToasts'
+> &
+  Pick<ToastComponentProps, 'id'> & {
+    style: ViewStyle | undefined;
+  };

src/providers/toast/provider.tsx

@@ -26,7 +26,11 @@ const ToasterContext = createContext<ToasterContextValue | null>(null);
  * Toast provider component
  * Wraps your app to enable toast functionality
  */
-export function ToastProvider({ insets, children }: ToastProviderProps) {
+export function ToastProvider({
+  insets,
+  maxVisibleToasts = 3,
+  children,
+}: ToastProviderProps) {
   const [toasts, dispatch] = useReducer(toastReducer, []);
 
   const isToastVisible = toasts.length > 0;
@@ -118,6 +122,7 @@ export function ToastProvider({ insets, children }: ToastProviderProps) {
               index={index}
               total={total}
               heights={heights}
+              maxVisibleToasts={maxVisibleToasts}
             />
           ))}
         </View>

src/providers/toast/toast-item-renderer.tsx

@@ -13,6 +13,7 @@ export const ToastItemRenderer = memo(
     index,
     total,
     heights,
+    maxVisibleToasts,
   }: ToastItemRendererProps) => {
     if (typeof toastItem.component !== 'function') {
       throw new Error(
@@ -25,6 +26,7 @@ export const ToastItemRenderer = memo(
       index,
       total,
       heights,
+      maxVisibleToasts,
       show,
       hide,
     });

src/providers/toast/types.ts

@@ -37,6 +37,12 @@ export interface ToastProviderProps {
    *   - Android: { top: 12, bottom: 12, left: 12, right: 12 }
    */
   insets?: ToastInsets;
+  /**
+   * Maximum number of visible toasts before opacity starts fading
+   * Controls when toast items begin to fade out as they move beyond the visible stack
+   * @default 3
+   */
+  maxVisibleToasts?: number;
   /**
    * Children to render
    */
@@ -63,6 +69,12 @@ export interface ToastComponentProps {
    * Heights of all toast items, keyed by toast ID
    */
   heights: SharedValue<Record<string, number>>;
+  /**
+   * Maximum number of visible toasts before opacity starts fading
+   * Controls when toast items begin to fade out as they move beyond the visible stack
+   * @default 3
+   */
+  maxVisibleToasts?: number;
   /**
    * Show a new toast
    */
@@ -172,6 +184,12 @@ export interface ToastItemRendererProps {
    * Heights of all toast items, keyed by toast ID
    */
   heights: SharedValue<Record<string, number>>;
+  /**
+   * Maximum number of visible toasts before opacity starts fading
+   * Controls when toast items begin to fade out as they move beyond the visible stack
+   * @default 3
+   */
+  maxVisibleToasts?: number;
   /**
    * Show a new toast
    */