react-freeze

1.0.4 verified Sat Apr 25 auth: no javascript

Prevent React component subtrees from rendering using Suspense. Current stable version is 1.0.4. React Freeze allows freezing parts of the component tree without unmounting, preserving React state and native views (e.g., scroll position, input state, loaded images). It leverages React 17+'s Suspense mechanism and is primarily used with React Navigation in React Native to avoid unnecessary re-renders of hidden screens. Unlike simple conditional rendering, it retains DOM/native instances. Requires React >=17 and React Native >=0.64. Maintained by Software Mansion, the team behind react-native-screens and react-native-reanimated.

Common errors

error Error: Cannot freeze a component tree because React version is < 17. Please upgrade to React 17 or later. ↓

cause React Freeze requires React 17's Suspense mechanism.

fix

Upgrade React to version 17 or higher using: npm install react@17 react-dom@17

error Invariant Violation: Suspense is not supported in this environment. Ensure you are using React 17+ and React Native 0.64+. ↓

cause Environment does not support Suspense (e.g., older RN version).

fix

Upgrade React Native to 0.64+ and React to 17+.

error TypeError: react_freeze__WEBPACK_IMPORTED_MODULE_9__.Freeze is not a function ↓

cause Incorrect import syntax (default import instead of named import).

fix

Change to: import { Freeze } from 'react-freeze'

error export 'enableFreeze' was not found in 'react-freeze' ↓

cause enableFreeze is not exported from react-freeze; it's from react-native-screens.

fix

Import enableFreeze from 'react-native-screens' (v3.9.0+).

Warnings

gotcha Freeze component suspends rendering of children but does NOT unmount them; state is preserved, but any cleanup in useEffect (return function) will not run while frozen. ↓

fix Ensure side effects that require cleanup are not dependent on freeze/unfreeze cycles; consider using alternative patterns.

deprecated enableFreeze from react-native-screens may be deprecated in future versions; use Suspense-based freezing directly with react-freeze. ↓

fix Use <Freeze freeze={...}> directly in your components or navigate using react-native-screens' newer API.

gotcha Freeze only works with React 17+; using it with older React versions will cause a runtime error due to missing Suspense support. ↓

fix Upgrade React to version 17 or higher.

gotcha Enabling freeze in react-navigation via react-native-screens may affect gesture handling (e.g., slide-back) on the second-to-top screen; only the top screen is not frozen. ↓

fix Test gesture interactions thoroughly; future versions may improve this.

breaking React Native 0.64 or higher is required; earlier versions do not support the necessary Suspense architecture. ↓

fix Upgrade React Native to 0.64+.

Install

npm install react-freeze

yarn add react-freeze

pnpm add react-freeze

Imports

Freeze

wrong

import Freeze from 'react-freeze'

correct

import { Freeze } from 'react-freeze'

ESM default export is not available; only named export.

Freeze

wrong

const Freeze = require('react-freeze')

correct

const { Freeze } = require('react-freeze')

CommonJS require returns an object with Freeze property.

enableFreeze
wrong
```
import { enableFreeze } from 'react-freeze'
```
correct
```
import { enableFreeze } from 'react-native-screens'
```
enableFreeze is exported from react-native-screens >=3.9.0, not from react-freeze.
type FreezeProps
```
import type { FreezeProps } from 'react-freeze'
```
TypeScript types are bundled; FreezeProps includes freeze: boolean and children: ReactNode.

Quickstart

Shows how to wrap a component tree with Freeze and conditionally freeze it based on a prop, preventing re-renders when hidden.

import React from 'react';
import { Freeze } from 'react-freeze';

function HiddenScreen({ isHidden }) {
  return (
    <Freeze freeze={isHidden}>
      <ExpensiveComponent />
    </Freeze>
  );
}

function ExpensiveComponent() {
  // This component won't re-render while frozen
  return <div>Some content</div>;
}