Hydration Warnings with Swiper in Server-Side Rendered React Application

[elvismdev]

Hello Swiper community,

I'm encountering hydration warnings when using Swiper in a server-side rendered React application. I've tried various approaches to resolve this, including using suppressHydrationWarning, but I'm still facing issues.

Here's a summary of my setup:

1. I'm using Swiper in a React component that's initially rendered on the server.
2. On the client-side, React attempts to hydrate this component.
3. I'm getting the following warning in the console:

react-dom.development.js?ver=18.2.0:73 Warning: Expected server HTML to contain a matching <div> in <div>.
    at div
    at div
    at Ee (http://localhost:10033/wp-content/plugins/msw-event-calendar/build/frontend.2260d4415b5a043d1bf7.js?ver=2260d4415b5a043d1bf7:2:106502)
printWarning @ react-dom.development.js?ver=18.2.0:73
error @ react-dom.development.js?ver=18.2.0:47
warnForInsertedHydratedElement @ react-dom.development.js?ver=18.2.0:10509
didNotFindHydratableInstance @ react-dom.development.js?ver=18.2.0:11468
warnNonhydratedInstance @ react-dom.development.js?ver=18.2.0:12395
tryToClaimNextHydratableInstance @ react-dom.development.js?ver=18.2.0:12544
updateHostComponent @ react-dom.development.js?ver=18.2.0:19941
beginWork @ react-dom.development.js?ver=18.2.0:21667
beginWork$1 @ react-dom.development.js?ver=18.2.0:27475
performUnitOfWork @ react-dom.development.js?ver=18.2.0:26606
workLoopSync @ react-dom.development.js?ver=18.2.0:26515
renderRootSync @ react-dom.development.js?ver=18.2.0:26483
performConcurrentWorkOnRoot @ react-dom.development.js?ver=18.2.0:25787
workLoop @ react.development.js?ver=18.2.0:2653
flushWork @ react.development.js?ver=18.2.0:2626
performWorkUntilDeadline @ react.development.js?ver=18.2.0:2920
react-dom.development.js?ver=18.2.0:12517 Uncaught Error: Hydration failed because the initial UI does not match what was rendered on the server.
    at throwOnHydrationMismatch (react-dom.development.js?ver=18.2.0:12517:11)
    at tryToClaimNextHydratableInstance (react-dom.development.js?ver=18.2.0:12545:9)
    at updateHostComponent (react-dom.development.js?ver=18.2.0:19941:7)
    at beginWork (react-dom.development.js?ver=18.2.0:21667:16)
    at HTMLUnknownElement.callCallback (react-dom.development.js?ver=18.2.0:4151:16)
    at Object.invokeGuardedCallbackDev (react-dom.development.js?ver=18.2.0:4200:18)
    at invokeGuardedCallback (react-dom.development.js?ver=18.2.0:4264:33)
    at beginWork$1 (react-dom.development.js?ver=18.2.0:27500:9)
    at performUnitOfWork (react-dom.development.js?ver=18.2.0:26606:14)
    at workLoopSync (react-dom.development.js?ver=18.2.0:26515:7)

I've tried adding suppressHydrationWarning={true} to various elements, including:

• The Swiper component: <Swiper suppressHydrationWarning={true} />
• The SwiperSlide components: <SwiperSlide suppressHydrationWarning={true} />
• Various div elements within the component

However, none of these attempts have resolved the warning.

My question is: What's the recommended approach for using Swiper in a server-side rendered React application to avoid these hydration warnings? Is there a specific way to initialize Swiper that prevents these issues?

Any guidance or best practices for this scenario would be greatly appreciated. Thank you!

Here below my current code:

// js/src/components/EventBanner.tsx

import React, {useState, useEffect} from 'react';
import {__} from '@wordpress/i18n';
import {Swiper, SwiperSlide} from 'swiper/react';
import {Navigation, A11y} from 'swiper/modules';
import type {Swiper as SwiperType} from 'swiper';

// Import Swiper styles
import 'swiper/css';
import 'swiper/css/navigation';

interface Event {
  id: number;
  category: {
	full: string;
	parent: string;
	child: string;
  };
  track_name: string;
  country: string;
  round_number: number;
  date: string;
  formatted_date: string;
  is_this_week: boolean;
}

interface EventBannerProps {
  events: Event[];
}

export const EventBanner: React.FC<EventBannerProps> = ( {events = []} ) => {
	const [ isThisWeek, setIsThisWeek ] = useState( events.length > 0 ? events[ 0 ].is_this_week : false );
	const [ isClient, setIsClient ] = useState( false );

	useEffect( () => {
		setIsClient( true );
	}, [] );

	const handleSlideChange = ( swiper: SwiperType ) => {
		if ( events[ swiper.activeIndex ] ) {
			setIsThisWeek( events[ swiper.activeIndex ].is_this_week );
		}
	};

	const pluginUrl = window.mswEventBannerData?.pluginUrl || '';

	if ( 0 === events.length ) {
		return null;
	}

	const renderEventSlide = ( event: Event ) => (
		<div className="msw-event-item">
			<div className="msw-event-item-content">
				<div className="msw-event-category">
					<span dangerouslySetInnerHTML={{__html: event.category.full}} />
					<img
						src={`${pluginUrl}/build/assets/flags/4x3/${event.country.toLowerCase()}.svg`}
						alt={event.country}
						className="msw-event-country-flag"
					/>
				</div>
				<div className="msw-event-subtitle">
					{event.track_name} (#{event.round_number})
				</div>
				<div className="msw-event-date">
					{__( 'Race Date:', 'msw-event-calendar' )} <span>{event.formatted_date}</span>
				</div>
			</div>
		</div>
	);

	return (
		<div className="msw-event-banner">
			<div className="msw-event-banner-inner">
				<div className="msw-event-this-week">
					{isThisWeek ? (
						<>
							<span>WEEK</span>
							<span>THIS</span>
						</>
					) : (
						<>
							<span>UP</span>
							<span>COMING</span>
						</>
					)}
				</div>
				<div className="msw-event-content">
					{isClient ? (
						<Swiper
							modules={[ Navigation, A11y ]}
							spaceBetween={0}
							slidesPerView={3}
							navigation={{
								nextEl: '.msw-swiper-button-next',
								prevEl: '.msw-swiper-button-prev',
							}}
							a11y={{
								prevSlideMessage: __( 'Previous events', 'msw-event-calendar' ),
								nextSlideMessage: __( 'Next events', 'msw-event-calendar' ),
							}}
							breakpoints={{
								320: {slidesPerView: 1},
								768: {slidesPerView: 2},
								1024: {slidesPerView: 3},
							}}
							onSlideChange={handleSlideChange}
						>
							{events.map( event => (
								<SwiperSlide key={event.id}>{renderEventSlide( event )}</SwiperSlide>
							) )}
						</Swiper>
					) : (
						<div className="swiper swiper-initialized swiper-horizontal">
							<div className="swiper-wrapper">
								{events.map( event => (
									<div className="swiper-slide" key={event.id}>
										{renderEventSlide( event )}
									</div>
								) )}
							</div>
						</div>
					)}
				</div>
				<div className="msw-swiper-navigation">
					<div className="msw-swiper-button-prev swiper-button-disabled" aria-label={__( 'Previous events', 'msw-event-calendar' )}>
						<i className="cs-icon-chevron-left"></i>
					</div>
					<div className="msw-swiper-button-next" aria-label={__( 'Next events', 'msw-event-calendar' )}>
						<i className="cs-icon-chevron-right"></i>
					</div>
				</div>
			</div>
		</div>
	);
};

And here is my PHP code which renders the initial HTML to be hydrated:

// templates/event-banner.php

<div class="msw-event-banner">
	<div class="msw-event-banner-inner">
		<div class="msw-event-this-week">
			<?php if ( ! empty( $events ) && $events[0]['is_this_week'] ) : ?>
				<span>WEEK</span><span>THIS</span>
			<?php else : ?>
				<span>UP</span><span>COMING</span>
			<?php endif; ?>
		</div>
		<div class="msw-event-content">
			<div class="swiper swiper-initialized swiper-horizontal">
				<div class="swiper-wrapper">
					<?php foreach ( $events as $event ) : ?>
						<div class="swiper-slide">
							<div class="msw-event-item">
								<div class="msw-event-item-content">
									<div class="msw-event-category">
										<span><?php echo wp_kses_post( $event['category']['full'] ); ?></span>
										<img
											src="<?php echo esc_url( MSW_EVENT_CALENDAR_URL . '/build/assets/flags/4x3/' . strtolower( $event['country'] ) . '.svg' ); ?>"
											alt="<?php echo esc_attr( $event['country'] ); ?>"
											class="msw-event-country-flag"
										/>
									</div>
									<div class="msw-event-subtitle">
										<?php echo esc_html( $event['track_name'] ); ?> (#<?php echo esc_html( $event['round_number'] ); ?>)
									</div>
									<div class="msw-event-date">
										<?php esc_html_e( 'Race Date:', 'msw-event-calendar' ); ?> <span><?php echo esc_html( $event['formatted_date'] ); ?></span>
									</div>
								</div>
							</div>
						</div>
					<?php endforeach; ?>
				</div>
			</div>
		</div>
		<div class="msw-swiper-navigation">
			<div class="msw-swiper-button-prev swiper-button-disabled" aria-label="<?php esc_attr_e( 'Previous', 'msw-event-calendar' ); ?>"><i class="cs-icon-chevron-left"></i></div>
			<div class="msw-swiper-button-next <?php echo ( count( $events ) <= 3 ) ? ' swiper-button-disabled' : ''; ?>" aria-label="<?php esc_attr_e( 'Next', 'msw-event-calendar' ); ?>"><i class="cs-icon-chevron-right"></i></div>
		</div>
	</div>
</div>