DEV Community

Cover image for Gatsby.js Browser APIs Explained: wrapPageElement vs wrapRootElement
Alex Crocker
Alex Crocker

Posted on

Gatsby.js Browser APIs Explained: wrapPageElement vs wrapRootElement

Gatsby.js is a powerful and flexible React framework that's focused on generating static pages and content from various external data sources at build time. It has a suite of powerful browser and node apis to manipulate data and create any page you might need.

Today I'm going to explain in-depth the difference between two fundamental browser apis that you should know, wrapPageElement and wrapRootElement.

Both of these browser apis are typically defined in the gatsby-browser.js file in the root of the project, but you can export both functions from gatsby-ssr.js as well in some cases without having to duplicate the code.

wrapPageElement is for layouts

First, the wrapPageElement api is ideal for base layouts that every page has. It's not necessary to use this function, but if you don't want to have to add your base layout component to every page of your site, then using this api is a good way to save some typing. Under the hood, this is what gatsby-plugin-layout is using, so now you can remove that unnecessary plugin.

wrapRootElement is for providers

Finally, the wrapRootElement api is designed for wrapping your core application with all of your various providers. In the example source code below, I am using the react-alert NPM package, which provides a convenient provider for us to demonstrate this api's usage. React Alert is a user-friendly library which provides hooks for customizing and displaying various alerts and notifications to the user.

To sum up, Gatsby has plenty of other browser apis, but wrapPageElement and wrapRootElement are the two you will probably be using most often in your sites. If you just remember that wrapPageElement is for layouts and wrapRootElement is for providers, you will be on your way to being a Gatsby expert in no time!

Source Code

import React from "react"

// Base Layout
import { Layout } from "./src/layouts/"

// react-alert
import { transitions, positions, Provider as AlertProvider } from "react-alert"
import AlertTemplate from "react-alert-template-basic"

const alertOptions = {
    position: positions.TOP_RIGHT,
    timeout: 5000,
    offset: "30px",
    transition: transitions.FADE,

export const wrapPageElement = ({ element }) => <Layout>{element}</Layout>

export const wrapRootElement = ({ element }) => (
    <AlertProvider template={AlertTemplate} {...alertOptions}>
Enter fullscreen mode Exit fullscreen mode

Top comments (3)

emekaorji profile image

I'm sorry, but this is not explanatory at all, take out time to understand things before you post because this gives some people a headache.

I clicked this link hoping to find answers and it's like I'm back to the Gatsby docs page but with a different layout

crock profile image
Alex Crocker

I'm sorry you feel that way, but maybe you should try to learn React basics first before diving into a framework. Others seem to enjoy this content and it ranks first on Google when searching for the difference between wrapPageElement and wrapRootElement, which are both Gatsby-specific functions.

It's not meant to be an extensive article, but just a quick summary of the primary difference between the two with a code sample.

emekaorji profile image

Yes I understand..

It just needs better in-depth explanation. If something is to be explained, it should be done well.

It helps the reader.
If it is heavy to write about two APIs, just write one instead and explain that one thing well. Cause one of the most annoying things about articles is seeing a header that says one thing and a content that says something else. It kills expectation.

And yes, I use a number of frameworks, understand react and use the wrapPageElement and wrapRootElement, but every now and then one needs to grasp a point really quick and refers to a doc, post, blog or a post that may have been written by himself.