DEV Community: Edgardo Mota

Solving a Hydration Error in Next.js with next-themes

Edgardo Mota — Sun, 24 Aug 2025 14:36:16 +0000

When developing applications with Next.js, implementing a theme system (light/dark mode) is a common requirement. The next-themes library is the standard solution for this task, but its interaction with Server-Side Rendering (SSR) can introduce hydration errors if not managed correctly.

This post documents a specific hydration error encountered while developing a theme-switching component and presents the applied solution.

Context and Initial Code

The goal was to create a simple ThemeToggle button that would switch between light and dark themes, displaying a sun or moon icon based on the current state.

The component was initially implemented as follows:

// src/components/ui/ThemeToggle.tsx (Initial version with error)
"use client";

import { Moon, Sun } from "lucide-react";
import { useTheme } from "next-themes";
import { Button } from "@/components/ui/button";

const ThemeToggle = () => {
  const { setTheme, resolvedTheme } = useTheme();

  const toggleTheme = () => {
    const newTheme = resolvedTheme === "dark" ? "light" : "dark";
    setTheme(newTheme);
  };

  return (
    <Button variant="ghost" size="icon" onClick={toggleTheme}>
      {resolvedTheme === "dark" ? (
        <Sun className="h-[1.2rem] w-[1.2rem]" />
      ) : (
        <Moon className="h-[1.2rem] w-[1.2rem]" />
      )}
      <span className="sr-only">Toggle theme</span>
    </Button>
  );
};

export { ThemeToggle };

The Problem: Conditional Hydration Error

This component functioned correctly during client-side navigation. However, upon reloading the page F5 with the dark theme enabled, a hydration error occurred: Hydration failed because the server rendered HTML didn't match the client.

The error did not occur when reloading the page in the light theme (the system's default).

Root Cause Analysis

The mismatch arises from the state disparity between the server and the client.

Server-Side Render (SSR): The server has no access to the browser's localStorage, where next-themes persists the user's preference. Therefore, the server renders the page using the default theme (in this case, "system", which resolved to "light"). As a result, the HTML sent to the browser contained the <Moon /> icon.
Client-Side Render: Upon page load, the next-themes script executes, reads the "dark" value from localStorage, and updates the theme state.
React Hydration Process: React then attempts to "hydrate" the server-rendered HTML. During this process, the ThemeToggle component's code runs on the client. The useTheme hook now correctly reports that resolvedTheme is "dark", so the component logic determines that the <Sun /> icon should be rendered. At this point, React detects an inconsistency: the server rendered <Moon />, but the client expected to render <Sun />. This triggers the hydration failure.

Solution: Deferring Client-Dependent Rendering

To resolve this mismatch, we must ensure that the initial client-side render matches what the server sent. The strategy is to delay rendering the theme-dependent UI until the component has successfully mounted on the client.

This is achieved using the useState and useEffect hooks.

// src/components/ui/ThemeToggle.tsx (Corrected version)
"use client";

import { useState, useEffect } from "react";
import { Moon, Sun, Loader2 } from "lucide-react";
import { useTheme } from "next-themes";
import { Button } from "@/components/ui/button";

const ThemeToggle = () => {
  const { setTheme, resolvedTheme } = useTheme();
  const [hasMounted, setHasMounted] = useState(false);

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

  const toggleTheme = () => {
    const newTheme = resolvedTheme === "dark" ? "light" : "dark";
    setTheme(newTheme);
  };

  if (!hasMounted) {
    return (
      <Button variant="ghost" size="icon" disabled>
        <Loader2 className="h-[1.2rem] w-[1.2rem] animate-spin" />
        <span className="sr-only">Loading...</span>
      </Button>
    );
  }

  return (
    <Button variant="ghost" size="icon" onClick={toggleTheme}>
      {resolvedTheme === "dark" ? (
        <Sun className="h-[1.2rem] w-[1.2rem]" />
      ) : (
        <Moon className="h-[1.2rem] w-[1.2rem]" />
      )}
      <span className="sr-only">Toggle theme</span>
    </Button>
  );
};

export { ThemeToggle };

Key Changes:

A hasMounted state is introduced, initialized to false.
A useEffect hook with an empty dependency array runs only on the client after the initial mount, setting hasMounted to true.
During SSR and the initial client render (before useEffect runs), the component renders a placeholder loading Loader2. This output is consistent between the server and the client, preventing the mismatch.
Once mounted, the component re-renders. Now that hasMounted is true, it safely displays the correct UI based on the now-reliable resolvedTheme.

The useState and useEffect pattern provides a solution for aligning server and client renders when dealing with state that is only available in the browser. It prevents hydration errors by ensuring the initial HTML is identical and defers the rendering of dynamic UI until the client's state is known and reliable.

I'm interested to hear about strategies other developers have implemented. What other solutions or custom hooks have you applied to manage hydration errors of this nature in your Next.js projects?

Case Study: A Complete User Flow in Next.js 15, from useSearchParams to Server Actions

Edgardo Mota — Sat, 23 Aug 2025 17:44:54 +0000

This article details the implementation of a complete user flow in Next.js 15, from selecting a service on the homepage to requesting a specific package on a details page. It covers the technique of passing state between pages using useSearchParams, conditional rendering based on the URL, and managing user interaction through a modal that communicates with a Server Action to process the request. The goal is to present a practical case study on architectural decisions, code organization, and the lessons learned along the way.

Tech Stack & Key Dependencies

The tool selection was focused on performance, type safety, and developer experience.

Framework: Next.js 15 (@next/15.4.6) with App Router and Turbopack.
Language: TypeScript (@typescript/5).
Styling: Tailwind CSS v4 (@tailwindcss/4).
UI Components:
- Headless Primitives: Radix UI (@radix-ui/react-select, @radix-ui/react-dialog) to ensure accessibility.
- Carousels: Embla Carousel (embla-carousel-react) for its lightweight and performant nature.
Backend & Forms:
- Server Logic: Server Actions.
- Validation: Zod (zod/4).
- Email Delivery: Nodemailer (nodemailer/7) & Mailchimp Marketing (@mailchimp/mailchimp_marketing).
Testing:
- Framework: Jest (jest/30).
- Environment: JSDOM (jest-environment-jsdom).
- Libraries: Testing Library (@testing-library/react, @testing-library/user-event).

Project Architecture

Code organization was a priority to ensure scalability and maintainability. A modular structure was adopted to clearly separate concerns:

src/
├── actions/ # Server-side logic (Server Actions)
├── app/ # Routes and layouts (App Router)
├── components/ # React Components
│ ├── sections/ # Page sections (composition)
│ └── ui/ # Base UI components (atomic)
├── data/ # Static data and content (single source of truth)
├── lib/ # Utility functions and config
├── schemas/ # Validation schemas with Zod
└── types/ # Global type definitions

(Note: Tests (__tests__) are co-located with the modules they test, facilitating discovery and maintenance.)

The Functional Requirement: A Context-Aware Navigation Flow

The goal was to design a user flow that wasn't generic. A user's selection on the main page had to pre-configure the state of a different details page (/cursos), displaying the relevant information immediately. In turn, selecting a specific package on this page needed to transfer its context to a request modal, minimizing friction for the user.

Step-by-Step Technical Implementation

How to pass the initial selection context between pages?

The useRouter hook from next/navigation was used in the source component (ServicesSection.tsx) to build a URL with a search parameter (?tab=...) that encodes the user's choice.

// src/components/sections/home/ServicesSection.tsx
import { useRouter } from 'next/navigation';

// ...

const router = useRouter();

const handleLearnMore = (serviceType: string) => {
  // Build and navigate to the URL with the selected service as the search parameter
  router.push(`/cursos?tab=${serviceType}`);
}

How does the destination page react to this context?

The destination component (CoursesSection.tsx) was implemented as a Client Component that uses the useSearchParams hook to read the tab parameter from the URL. This value is used to initialize the activeTab state, ensuring the correct content is displayed on the first render, even if the page is reloaded or the link is shared.

// src/components/sections/cursos/CoursesSection.tsx
import { useSearchParams } from 'next/navigation';
import { useState, useEffect } from 'react';

// ...

// Reads URL parameters from the client side
const searchParams = useSearchParams();
const tabFromUrl = searchParams.get('tab');

// A helper function to validate the parameter and return a safe value
const getValidatedTab = (tab: string | null): TabKey => {
  const validTabs = Object.keys(coursesData);
  if (tab && validTabs.includes(tab)) {
    return tab as TabKey;
  }
  return 'personalizado'; // Returns a default value if the parameter is invalid or null
};

// Initialize the component state directly from the URL
const [activeTab, setActiveTab] = useState<TabKey>(() => getValidatedTab(tabFromUrl));

// (Optional) Sync state if user navigates back/forward
useEffect(() => {
    setActiveTab(getValidatedTab(searchParams.get('tab')));
}, [searchParams]);

How to handle the final request securely and efficiently?

Selecting a package triggers a ServiceRequestModal. This component encapsulates the final conversion logic:

It receives the serviceName as a prop to personalize its content.
It presents a minimal form (only email) to reduce friction.
It uses useActionState to call the submitServiceRequest Server Action.
The loading state (pending) is automatically managed via a SubmitButton sub-component that uses useFormStatus.

// src/components/sections/cursos/ServiceRequestModal.tsx
'use client';

import React, { useEffect } from 'react';
import { useActionState, useFormStatus } from 'react';
import { Modal } from '@/components/ui/Modal';
import { Input } from '@/components/ui/Input';
import { Button } from '@/components/ui/Button';
import { submitServiceRequest } from '@/actions/serviceRequest';

// Subcomponent to access the 'pending' state
function SubmitButton() {
    const { pending } = useFormStatus();
    return (
        <Button type="submit" loading={pending} disabled={pending} fullWidth>
            {pending ? 'Enviando...' : 'Confirmar Solucitud'}
        </Button>
    );
}

export const ServiceRequestModal = ({ isOpen, onClose, serviceName }) => {
    // Link the form to the Server Action
    const [state, formAction] = useActionState(submitServiceRequest, { message: '', success: false });

    // Closes the modal automatically if the action was successful
    useEffect(() => {
        if (state?.success) {
            const timer = setTimeout(() => onClose(), 2000);
            return () => clearTimeout(timer);
        }
    }, [state, onClose]);

    return (
        <Modal isOpen={isOpen} onClose={onClose}>
            {state?.success ? (
                <p className="text-green-600">{state.message}</p>
            ) : (
                <>
                    <p>
                        Estás solicitando el paquete: <strong>{serviceName}</strong>
                    </p>
                    <form action={formAction} className="space-y-4">
                        <Input
                            name="email"
                            type="email"
                            placeholder="tu@correo.com"
                            required
                        />
                        {/* Pass the service name to the Server Action in a hidden way */}
                        <input type="hidden" name="serviceName" value={serviceName} />
                        <SubmitButton />
                        {state?.message && <p className="text-sm text-red-600">{state.message}</p>}
                    </form>
                </>
            )}
        </Modal>
    );
};

Alternative Approaches

The implemented solution using useSearchParams is effective for this use case, as it treats the URL as the source of truth, which is ideal for state that needs to be shareable and persistent. However, it's not the only way to solve this problem. I'm opening the discussion to the community:

Context API vs. URL State

In what scenarios would you have preferred using React's Context API to manage this state? An advantage could be avoiding URL "pollution," but with the downside of losing state on a page refresh.

Global State Libraries (Redux, Zustand)

For a flow like this, would you consider a global state library a viable option? Or would it be overkill for state that isn't truly "global" to the entire application?

Other Techniques?

Are there other patterns or tools within the Next.js ecosystem you would have considered for passing state between pages this way? I'd love to read about other implementations.

Resources & Contact

The source code is available for review. Technical feedback, suggestions for improvement via Issues, or Pull Requests are welcome.

For technical discussions or professional inquiries, you can find me on Linkedin.

Axero Frontend Challenge: Building a Dynamic Office Intranet Interface

Edgardo Mota — Sun, 27 Jul 2025 18:15:50 +0000

This is a submission for Frontend Challenge: Office Edition sponsored by Axero, Holistic Webdev: Office Space

Corporate Hub: Intelligent Intranet Dashboard

What I Built

We created Corporate Hub, a modern and intelligent corporate intranet dashboard that reimagines how employees interact with their workplace digital environment. Our goal was to build more than just another dashboard – we wanted to create a welcoming, intuitive space that feels like having a personal AI assistant helping you stay productive throughout your workday.

Key Features:

🤖 Intelligent Welcome Component: An AI-like messaging system that provides contextual reminders, follow-ups, and deadlines using natural language
📰 Smart News Carousel: Mobile-optimized news rotation with responsive design and accessibility features
📅 Integrated Event Management: Seamless calendar integration with smart notifications
👥 Team Discovery: New hires showcase with detailed employee profiles
🚀 Application Launcher: Quick access to corporate tools and external applications
🔗 Smart Quick Links: Categorized resource organization for efficient navigation
🌙 Dark Mode Support: Complete theming system with user preference persistence
♿ Accessibility First: WCAG 2.1 compliant with comprehensive keyboard navigation and screen reader support

Demo

🔗 Live Demo: Corporate Hub Dashboard

📂 Source Code: GitHub Repository

Screenshots:

Journey

The Vision

We started with a simple question: "What if your corporate intranet felt as welcoming and intelligent as a personal assistant?" This led us to focus on creating an experience that's both functional and emotionally engaging.

Technical Highlights We're Proud Of:

1. AI-Inspired Welcome Experience

// Natural language messaging with typing animation
const messages = [
  "Recuerda revisar la propuesta del cliente que quedó pendiente ayer.",
  "El equipo de diseño está esperando tu feedback sobre los mockups.",
  "La documentación técnica vence mañana, ¿ya tienes todo listo?"
];

We implemented a typing effect animation without external libraries, creating messages that feel conversational and human rather than robotic.

2. Mobile-First Responsive Design

Our news carousel adapts intelligently to different screen sizes:

Desktop: Full navigation with position indicators
Mobile: Clean interface with edge-to-edge images and simplified controls

3. Performance Optimization

Lazy loading for all dashboard components
React.memo for preventing unnecessary re-renders
Code splitting with dynamic imports
Optimized bundle size with manual chunk splitting

4. Accessibility Excellence

Complete keyboard navigation support
ARIA labels and live regions for screen readers
Focus management and skip links
Color contrast compliance (WCAG 2.1 AA)

Development Process:

Phase 1: Foundation 🏗️

Set up React + TypeScript + Vite stack
Implemented design system with Tailwind CSS
Created reusable component library

Phase 2: Core Features ⚡

Built responsive layout system
Developed news carousel with auto-rotation
Implemented event management integration

Phase 3: Intelligence Layer 🧠

Created the WelcomeHero component with AI-like messaging
Added contextual content based on user data
Implemented smart notifications system

Phase 4: Polish & Optimization ✨

Added comprehensive error boundaries
Implemented loading states and skeleton screens
Optimized for production deployment

Challenges Overcome:

TypeScript Compilation Issues: Resolved 60+ TypeScript errors for successful Netlify deployment
Mobile UX Optimization: Redesigned components specifically for touch interfaces
Performance Bottlenecks: Implemented lazy loading and memoization strategies
Accessibility Compliance: Ensured full keyboard navigation and screen reader support

What We Learned:

User Experience First: Technical excellence means nothing without great UX
Progressive Enhancement: Start with core functionality, then add intelligence
Performance Matters: Every millisecond counts in user perception
Accessibility is Essential: Inclusive design benefits everyone

Team Collaboration:

This project was built in collaboration with @jonathanbc10 combining our expertise in frontend development and user experience design.

Tech Stack:

Frontend: React 18, TypeScript, Vite
Styling: Tailwind CSS with custom design system
State Management: React Hooks with context
Testing: Vitest with React Testing Library
Deployment: Netlify with automatic CI/CD
Performance: Lazy loading, code splitting, memoization

License

This project is licensed under the MIT License.

Open Source Commitment

We believe in the power of open source software. Corporate Hub is freely available for:

✅ Personal and commercial use
✅ Modification and distribution
✅ Private use
✅ Learning and educational purposes

Feel free to fork, modify, and build upon our work. We'd love to see what you create!

Corporate Hub represents our vision of what modern workplace software should be: intelligent, accessible, and genuinely helpful. We believe that great software should feel less like a tool and more like a thoughtful colleague who's always there to help you succeed.