Conflicting libraries or plugins

Oct 13, 2025 by talynt.org 114 views

react-aria/interactions] "Uncaught Error: document is not defined" when using SSR and window is defined

Issue Summary

When using Server-Side Rendering (SSR) and the window object is defined, an error occurs as soon as a React-Aria component is added to the solution. This issue was encountered when adding a <Button /> component, but it also affects other components. The error message is "Uncaught Error: document is not defined." This problem may be related to the issue discussed in the Adobe React Spectrum GitHub repository (https://github.com/adobe/react-spectrum/issues/6534).

Expected Behavior

When using SSR, the solution should not throw an exception when the window object is defined. The expected behavior is that the React-Aria components should render correctly without any errors.

Current Behavior

When running the SSR, the solution throws an "Uncaught Error: document is not defined" exception. This issue affects the rendering of React-Aria components, making it difficult to use them in an SSR environment.

Possible Solution

To resolve this issue, it is essential to check not only if window is defined but also if document is defined. This ensures that the React-Aria components are only rendered when both window and document are available.

Context

Our solution uses both frontend and SSR, and it is crucial that the SSR works seamlessly like the frontend rendering. To achieve this, we can use a workaround by checking if the solution is running in an SSR environment using the useIsSSR hook and not loading the React-Aria components if it is.

Steps to Reproduce

To reproduce this issue, you can modify the ssrWorker.js file in your test-utils/src directory by adding the line window = {}; on line 25. This will cause most of your SSR test suite to crash, demonstrating the problem with most components when window is set but not document.

Version

The version of React-Aria being used is 1.7.1.

Browsers Affected

This issue is observed in Chrome and Firefox browsers.

Operating System

The issue is encountered on Windows 11.

Company/Team

The company/ team experiencing this issue is Avensia/Lyko.

Tracking Issue

There is no tracking issue associated with this problem.

Understanding the Issue

The error "Uncaught Error: document is not defined" occurs when the React-Aria components are rendered in an SSR environment where the window object is defined but the document object is not. This issue is not specific to the React-Aria library but is a general problem that can occur when using SSR and React components.

Possible Causes

There are several possible causes for this issue:

Incorrect use of window and document objects: The window and document objects are not always available in an SSR environment. When using these objects, it is essential to check if they are defined before accessing them.
Incompatible React-Aria version: The issue might be caused by an incompatible version of React-Aria. Upgrading or downgrading the version might resolve the problem.
Conflicting libraries or plugins: Conflicting libraries or plugins might be causing the issue. Checking for any conflicts and resolving them might resolve the problem.

Resolving the Issue

To resolve this issue, you can try the following:

Check for incompatible libraries or plugins: Verify that all libraries and plugins are compatible with each other and with the React-Aria version being used.
Upgrade or downgrade React-Aria version: Try upgrading or downgrading the React-Aria version to see if it resolves the issue.
Use useIsSSR hook: Use the useIsSSR hook to check if the solution is running in an SSR environment and not load the React-Aria components if it is.
Check for incorrect use of window and document objects: Verify that the window and document objects are not being used incorrectly in the React-Aria components.

Conclusion

The "Uncaught Error: document is not defined" issue occurs when using SSR and the window object is defined but the document object is not. This issue can be resolved by checking if both window and document are defined before rendering the React-Aria components. Additionally, using the useIsSSR hook to check if the solution is running in an SSR environment and not loading the React-Aria components if it is can also help resolve the issue.
Q&A: "Uncaught Error: document is not defined" when using SSR and window is defined

Q: What is the cause of the "Uncaught Error: document is not defined" issue when using SSR and window is defined?

A: The issue occurs when the React-Aria components are rendered in an SSR environment where the window object is defined but the document object is not. This is because the document object is not available in an SSR environment, and the React-Aria components are trying to access it.

Q: How can I resolve the "Uncaught Error: document is not defined" issue?

A: To resolve this issue, you can try the following:

Check for incompatible libraries or plugins: Verify that all libraries and plugins are compatible with each other and with the React-Aria version being used.
Upgrade or downgrade React-Aria version: Try upgrading or downgrading the React-Aria version to see if it resolves the issue.
Use useIsSSR hook: Use the useIsSSR hook to check if the solution is running in an SSR environment and not load the React-Aria components if it is.
Check for incorrect use of window and document objects: Verify that the window and document objects are not being used incorrectly in the React-Aria components.

Q: What is the useIsSSR hook, and how can I use it to resolve the issue?

A: The useIsSSR hook is a utility hook that allows you to check if the solution is running in an SSR environment. You can use this hook to conditionally load the React-Aria components only when the solution is not running in an SSR environment.

Here is an example of how you can use the useIsSSR hook to resolve the issue:

import { useIsSSR } from 'react-aria/hooks';

const MyComponent = () => {
  const isSSR = useIsSSR();

  if (isSSR) {
    return null; // or some other fallback component
  }

  return <Button />;
};

Q: Can I use a workaround to resolve the issue?

A: Yes, you can use a workaround to resolve the issue. One possible workaround is to check if both window and document are defined before rendering the React-Aria components. Here is an example of how you can do this:

import { useState, useEffect } from 'react';

const MyComponent = () => {
  const [windowDefined, setWindowDefined] = useState(false);
  const [documentDefined, setDocumentDefined] = useState(false);

  useEffect(() => {
    setWindowDefined(window !== undefined);
    setDocumentDefined(document !== undefined);
  }, []);

  if (!windowDefined || !documentDefined) {
    return null; // or some other fallback component
  }

  return <Button />;
};

Q: What are some best practices for using React-Aria in an SSR environment?

A: Here are some best practices for using React-Aria in an SSR environment:

Use the useIsSSR hook: Use the useIsSSR hook to check if the solution is running in an SSR environment and conditionally load the React-Aria components accordingly.
Check for incompatible libraries or plugins: Verify that all libraries and plugins are compatible with each other and with the React-Aria version being used.
Upgrade or downgrade React-Aria version: Try upgrading or downgrading the React-Aria version to see if it resolves any issues.
Use a fallback component: Use a fallback component when the solution is running in an SSR environment to prevent any errors from occurring.

By following these best practices and using the useIsSSR hook, you can ensure that your React-Aria components work seamlessly in both SSR and client-side rendering environments.