Gatsby Browser APIs

Usage

Implement any of these APIs by exporting them from a file named gatsby-browser.js in the root of your project.


APIs



Reference

disableCorePrefetching

Plugins can take over prefetching logic. If they do, they should call this to disable the now duplicate core prefetching logic.


onClientEntry

Called when the Gatsby browser runtime first starts.

Example

exports.onClientEntry = () => {
  console.log("We've started!")
  callAnalyticsAPI()
}

onInitialClientRender

Called when the initial (but not subsequent) render of Gatsby App is done on the client.

Example

exports.onInitialClientRender = () => {
  console.log("ReactDOM.render has executed")
}

onPreRouteUpdate

Called when changing location is started.

Parameters

destructured object
location {object}

A location object

action {object}

The “action” that caused the route change

Example

exports.onPreRouteUpdate = ({ location }) => {
  console.log("Gatsby started to change location", location.pathname)
}

onPrefetchPathname

Called when prefetching for a pathname is triggered. Allows for plugins with custom prefetching logic.

Parameters

destructured object
pathname {object}

The pathname whose resources should now be prefetched

getResourcesForPathname {object}

Function for fetching resources related to pathname


onRouteUpdate

Called when the user changes routes

Parameters

destructured object
location {object}

A location object

action {object}

The “action” that caused the route change

Example

exports.onRouteUpdate = ({ location }) => {
  console.log('new pathname', location.pathname)

  // Track pageview with google analytics
  window.ga(
    `set`,
    `page`,
    location.pathname + location.search + location.hash,
  )
  window.ga(`send`, `pageview`)
}

onRouteUpdateDelayed

Called when changing location is longer than 1 second.

Parameters

destructured object
location {object}

A location object

action {object}

The “action” that caused the route change

Example

exports.onRouteUpdateDelayed = () => {
  console.log("We can show loading indicator now")
}

onServiceWorkerActive

Inform plugins when a service worker has become active.

Parameters

destructured object
serviceWorker {object}

The service worker instance.


onServiceWorkerInstalled

Inform plugins when a service worker has been installed.

Parameters

destructured object
serviceWorker {object}

The service worker instance.


onServiceWorkerRedundant

Inform plugins when a service worker is redundant.

Parameters

destructured object
serviceWorker {object}

The service worker instance.


onServiceWorkerUpdateFound

Inform plugins of when a service worker has an update available.

Parameters

destructured object
serviceWorker {object}

The service worker instance.


registerServiceWorker

Allow a plugin to register a Service Worker. Should be a function that returns true.

Example

exports.registerServiceWorker = () => true

replaceComponentRenderer

Allow a plugin to replace the page component renderer. This api runner can be used to implement page transitions. See https://github.com/gatsbyjs/gatsby/tree/master/examples/using-page-transitions for an example of this.

Parameters

destructured object
props {object}

The props of the page.

loader {object}

The gatsby loader.


shouldUpdateScroll

Allow a plugin to decide if the “scroll” should update or not on a route change.

Parameters

destructured object
prevRouterProps {object}

The previous state of the router before the route change.

pathname {object}

The new pathname


wrapPageElement

Allow a plugin to wrap the page element.

This is useful for setting wrapper component around pages that won’t get unmounted on page change. For setting Provider components use wrapRootElement.

Note: There is equivalent hook in SSR API

Parameters

destructured object
element {object}

The “Page” React Element built by Gatsby.

props {object}

Props object used by page.

Example

import React from "react"
import Layout from "./src/components/Layout"

export const wrapPageElement = ({ element, props }) => {
  // props provide same data to Layout as Page element will get
  // including location, data, etc - you don't need to pass it
  return <Layout {...props}>{element}</Layout>
}

wrapRootElement

Allow a plugin to wrap the root element.

This is useful to setup any Providers component that will wrap your application. For setting persistent UI elements around pages use wrapPageElement.

Note: There is equivalent hook in SSR API

Parameters

destructured object
element {object}

The “Root” React Element built by Gatsby.

Example

import React from "react"
import { Provider } from "react-redux"

import createStore from "./src/state/createStore"
const store = createStore()

export const wrapRootElement = ({ element }) => {
  return (
    <Provider store={store}>
      {element}
    </Provider>
  )
}