Next.js 13 "window is not defined"

Matthew C.

—March 15, 2024

The Problem

In Next.js version 13+, you may have encountered the following error when trying to use the browser API window object:

Unhandled Runtime Error
Error: window is not defined

This error occurs because components are server-rendered by default. Components are pre-rendered into HTML on the server before being sent to the client. The window object is not available on the server.

The Solution

If you want to use browser APIs like window, use a client component. To make your component a client component add the React "use client" directive at the top of your component file, above your imports.

The client components will still be pre-rendered on the server and then hydrated on the client. To make sure that the code that uses the window object only runs on the client, use the useEffect hook, an event handler, lazy load the component, or do a check for the window object.

Use useEffect

You can access the window object once the component is mounted inside a useEffect callback function:

useEffect(() => {
    window.alert("window.alert from client component");
}, []);

Use an Event Handler

You can also access the window object in event handlers because event handlers are added to the pre-rendered HTML on the client by React. This process is called hydration.

<button onClick={() => window.alert("window.alert from client component")}>
  Click me
</button>

Check If window is Defined

You can also check if the window object is defined:

if (typeof window !== "undefined") {
  window.alert("window.alert from client component");
}

Be careful about using this method as it can cause hydration errors if it causes a difference between the HTML that’s pre-rendered on the server and the HTML that’s first rendered on the client when the component is hydrated.

Lazy Load Your Client Component and Disable SSR

If you want to access the window object at the top level of your component, you can lazy load your client component and disable pre-rendering on the server to make sure that it’s only rendered on the client. However, this may make the initial page load slower. This approach is useful when using client-only libraries or if you only need to load the client component after a certain user action.