React SSR pitfalls in building adaptive layouts

Oct 6, 2019 • 4 min read


While working on migration of part our main web-site to gatsby, we faced really weird problem: one of a links in navigation menu wasn't styled on initial load. It was reproducible only on the desktop.

Navigation menu with unstyled link

Once you opened some other page (using client-side routing), styles get in place 🤯.

The fact that component, responsible for this menu, worked absolutely fine in the old app (which is using nextjs), made everything even more weird 👻.


Without a second thought I opened DOM inspector and discovered that this link had css-classes related to mobile menu, while I was obviously on the desktop 🤪.

"React messes up DOM during hydration" - I thought to myself. It was hard to believe: such crucial issue should have been discovered long time ago, and everything is fine IN THE OLD APP.

I revised hydration contract:

React expects that the rendered content is identical between the server and the client.

I dig into source code of the component 🕵️‍♂️:

// simplified NavBar.js
import React from 'react'
import Media from 'react-media'

export const NavBar = () => (
  <Media queries={{ maxWidth: 599 }}>
    {matches => (matches ? <MobileNav /> : <DesktopNav />)}


Do you see a problem here?

  • react-media is used to serve different markup for desktop and mobile
  • we are migrating our app to gatsby, which means all our pages are statically built (SSR is happening during build time). And on this stage, we obviously do not have any information about width of the screen. By default react-media matches all media queries, so in our case we build mobile layout.

This results in next workflow:

  1. desktop browser requests page and receive mobile html (user sees it on first contentful paint)
  2. react messes up DOM during hydration (absolutely legally, since we produced 2 different trees on the "server" and client)

How to fix this?

To avoid such problems we can:

  • prefer regular css media queries to matchMedia

    Even if you cannot style same piece of html to fit your adaptive design, you can "duplicate" it (html) and display one "copy" per breakpoint.

    let DesktopOnly = styled.div`
      @media (max-width: 599px) {
        display: none;
    let MobileOnly = styled.div`...`
    export const NavBar = () => (
          <MobileNav />
          <DesktopNav />

    In this case not only you will avoid problems with hydration, but also end-user will get better experience: there will be no layout flickering during page load, since browser will render the page according to your html/css, and hydration will give it life.

  • only in case the approach above doesn't work for you, use react-media (or similar solutions). E.g.:

    • SEO might suffer (I haven't faced such problems, but I assume that duplication of content, its growth... can influence it 💁‍♂️. Write a comment if you are aware of such cases)
    • performance might suffer, in case you render some complex element only for the desktop.

      ATTENTION PLEASE! Do not optimize prematurely! Always measure performance before you introduce any improvements. The fact that react will have to render 50 more html elements shouldn't bother you.
    • something else might suffer 🤷‍♂️

But what about problems with hydration we experienced using second approach?

Well, as I mentioned at the beginning, such issue shouldn't have been left out, so it has a solution - two-pass rendering:

  • choose a default layout you'd like to use by default:
    • if you are using runtime SSR, you can do it based on User Agent
    • for static sites based on usage statistics (in most cases it should be mobile, since devices are less performant, and it doesn't make sense to make them render tree twice)
  • render three using this default during SSR and client hydration
  • run an extra render in case actual layout didn't match default one

Official documentation suggests to use state variable to implement this and react-media also supports this via defaultMatches prop:

export const NavBar = () => (
    queries={{ mobile: { maxWidth: 599 } }}
    defaultMatches={{ mobile: true }}
    {matches => ( ? <MobileNav /> : <DesktopNav />)}


"Why didn't you experience the same issue in your old app?" - a careful reader might wonder 🤨. Indeed, we use SSR there as well and do not use knowledge about browser (User Agent). To be honest, I didn't dig into legacy project in order to learn its secrets. But I guess it's about some extra render initiated by parent components 😬.

Next reads

Better late than never

Jan 10, 2019 • 4 min read

I have been thinking about developing my personal blog for a least 5 years already. Finally I have enough experience and comfortable toolchain. Here is my first try to post something here ✨🥳🎉

Build "Related Reads" for your gatsby blog

Apr 30, 2020 • 3 min read

In this article I will tell how to build "Related Reads" section for a Gatsby blog, like the one you can find at the bottom of this page.

Refactor like no one is watching

Apr 19, 2020 • 6 min read

Short story about using AST transformation to refactor the code. Like some codemods you might used.