react-freeze

library1.0.4jsnpmunverified

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.

web-framework

npm install react-freeze

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-FREEZE

react-freeze

web-frameworkjavascriptv1.0.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Freeze

✓ import { Freeze } from 'react-freeze'

✗ import Freeze from 'react-freeze'

ESM default export is not available; only named export.

Freeze

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

✗ const Freeze = require('react-freeze')

CommonJS require returns an object with Freeze property.

enableFreeze

✓ import { enableFreeze } from 'react-native-screens'

✗ import { enableFreeze } from 'react-freeze'

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.

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>; }

Debug

Known issues

gotchaFreeze 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.

affects: >=1.0.0

deprecatedenableFreeze 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.

affects: >=3.9.0

gotchaFreeze 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.

affects: >=1.0.0

gotchaEnabling 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.

affects: >=3.9.0

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

fix

Upgrade React Native to 0.64+.

affects: >=1.0.0

Errors

Common errors & fixes

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

React Freeze requires React 17's Suspense mechanism.

fix

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

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

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

fix

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

TypeError: react_freeze__WEBPACK_IMPORTED_MODULE_9__.Freeze is not a function

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

fix

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

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

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

fix

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

Upgrade

Version history

1.0.4latest on npm

Audit

Dependencies

reactrequiredPeer dependency; requires React 17 or higher to use Suspense

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/software-mansion/react-freeze ↗

packagehttps://www.npmjs.com/package/react-freeze ↗

homepagehttps://react-freeze.vercel.app ↗