Swiper + React SSR: watchOverflow Hydration Behavior

Hydration Behavior of watchOverflow

In a React SSR environment, watchOverflow does not execute on the server because it relies on DOM measurements (such as offsetWidth), which are unavailable during server-side rendering. The server produces static HTML; the actual logic for overflow detection only triggers once the Swiper instance initializes on the client during hydration.

If you observe the overflow check running twice, it is rarely an SSR-specific bug. Instead, it is typically caused by React 18 Strict Mode in development, which intentionally mounts, unmounts, and remounts components to ensure effect cleanup, or by a failure to destroy the previous Swiper instance during a state-driven re-render.

Preventing Duplicate Execution

To ensure the overflow check and general initialization occur only once (or are cleaned up correctly), implement a strict destruction pattern in your useEffect hook. This prevents orphaned instances from maintaining event listeners or conflicting with the new hydration instance.

import { useEffect, useRef } from 'react';
import Swiper from 'swiper';

const SwiperComponent = () => {
  const swiperRef = useRef(null);

  useEffect(() => {
    // Initialize Swiper
    const swiper = new Swiper('.swiper-container', {
      watchOverflow: true,
      // other config
    });
    
    swiperRef.current = swiper;

    // Cleanup function to prevent duplicate instances
    return () => {
      if (swiperRef.current) {
        swiperRef.current.destroy();
        swiperRef.current = null;
      }
    };
  }, []);

  return <div className="swiper-container">...</div>;
};

SSR Guidelines and Assumptions

• Server-Side State: Assume any overflow-related classes (like those hiding navigation buttons) cannot be accurately determined on the server. These should be applied exclusively on the client.
• Dynamic Content: If your slides are loaded asynchronously after hydration, watchOverflow may not trigger correctly. You must call swiper.update() after the content is rendered to force a re-calculation.
• Strict Mode: To verify if the "double run" is a development artifact, disable React.StrictMode. If the behavior disappears, the cleanup pattern above is the correct resolution.

Diagnostic Request: Are you using the swiper/react component wrapper or initializing the Swiper Core API manually? The wrapper handles some internal cleanup, but manual initialization requires the explicit .destroy() pattern shown above.