React Shallow Equal Utilities

Common errors

• TypeError: Cannot destructure property 'propsEqual' of ... as it is undefined.

  cause Attempting to import `propsEqual` using CommonJS `require` syntax on a module that might be primarily ES Module (ESM) or packaged incorrectly for CJS, or the package path is incorrect.
  fix Ensure you are using the correct ES Module import syntax: `import { propsEqual } from 'react-shallow-equal';`. If using CommonJS, verify the package exports named properties correctly or adjust your build system (e.g., Babel/Webpack) to handle ESM imports.

• Component not re-rendering when nested data changes.

  cause Shallow equality (used by `propsEqual` and `PureComponent`/`React.memo`) only compares references for non-primitive values. If a nested object's contents change but its reference remains the same, the shallow comparison will return true (meaning 'no change'), and the component will not re-render.
  fix Adopt immutable data patterns. When updating state or props that contain nested objects, always create new object references for the parent object(s) up to the root if any nested property changes. For example, use spread syntax (`{...prevObj, nested: {...prevObj.nested, prop: newValue}}`) to create new objects.

Warnings

• breaking This package is considered abandoned, having not been updated in over 8 years. It is highly recommended to use built-in React features like `React.PureComponent` for class components or `React.memo` with `useCallback`/`useMemo` for functional components, which provide similar and often more optimized shallow comparison behavior.
  Fix: Migrate to `React.PureComponent` or `React.memo` for component optimization. For custom shallow comparisons, consider implementing a modern `shallowEqual` utility or using `lodash.isequal` with a shallow customizer.
• gotcha Shallow equality checks only compare the values of properties at the first level of an object or array. For nested objects or arrays, it only compares their references, not their contents. If a nested object changes its internal values but maintains the same reference, `propsEqual` (and `PureComponent`/`React.memo`) will not detect a change and prevent re-rendering, potentially leading to stale UI.
  Fix: Ensure that state and props are immutable. When updating nested data, always create new objects/arrays at every level that changes to ensure reference equality checks correctly detect updates. For deep comparisons, a custom deep equality function or a library like `lodash.isequal` is necessary.
• deprecated The functionality provided by `react-shallow-equal` has been largely superseded by native React features. `React.PureComponent` (introduced in React 15.3.0) and `React.memo` (introduced in React 16.6.0) offer built-in shallow comparison for `props` and `state` out of the box.
  Fix: For new projects or refactoring, prefer using `React.PureComponent` for class components or wrapping functional components with `React.memo`. These are maintained by the React team and integrate seamlessly with the reconciliation process.

Install

• npm install react-shallow-equal npm
• yarn add react-shallow-equal yarn
• pnpm add react-shallow-equal pnpm

Imports

• propsEqual
  wrong:

  const propsEqual = require('react-shallow-equal').propsEqual;

  correct:

  import { propsEqual } from 'react-shallow-equal';

  Primary utility for comparing component props. While the library might support CJS, ESM import is shown in documentation.
• elementsEqual
  wrong:

  import elementsEqual from 'react-shallow-equal';

  correct:

  import { elementsEqual } from 'react-shallow-equal';

  Used for comparing React elements. It is a named export, not a default export.
• stylesEqual
  wrong:

  const stylesEqual = require('react-shallow-equal');

  correct:

  import { stylesEqual } from 'react-shallow-equal';

  Specialized utility for comparing style objects, useful in React Native or when inline styles are passed as props.

Quickstart

Demonstrates `propsEqual` usage within a React component's `shouldComponentUpdate` to prevent unnecessary re-renders based on shallow property comparison, similar to `PureComponent`.

import React, { PureComponent } from 'react';
import { propsEqual } from 'react-shallow-equal';

class MyOptimizedComponent extends PureComponent {
  // In a traditional React component (not PureComponent), you would implement this:
  // shouldComponentUpdate(nextProps, nextState) {
  //   // Only re-render if props are NOT shallowly equal or state has changed
  //   return !propsEqual(this.props, nextProps) || !shallowEqual(this.state, nextState);
  // }

  render() {
    // Simulate rendering based on props, e.g., from an API call or parent component
    const { data, isActive, onAction } = this.props;
    return (
      <div>
        <h2>Item: {data.name}</h2>
        <p>Status: {isActive ? 'Active' : 'Inactive'}</p>
        <button onClick={onAction}>Perform Action</button>
        <p>Last updated: {new Date().toLocaleTimeString()}</p>
      </div>
    );
  }
}

// Example of usage in a parent component
function App() {
  const [count, setCount] = React.useState(0);
  const [itemData, setItemData] = React.useState({ id: 1, name: 'Example Item' });

  const handleAction = React.useCallback(() => {
    console.log('Action performed!');
    setCount(prev => prev + 1);
  }, []);

  // This prop object will be new on every render, but MyOptimizedComponent
  // would only re-render if data.name or isActive actually changed values
  // if using propsEqual inside shouldComponentUpdate.
  // With PureComponent, it handles this automatically with its own shallow comparison.
  const componentProps = {
    data: itemData,
    isActive: count % 2 === 0,
    onAction: handleAction,
    extraProp: count // This will cause PureComponent to re-render every time it changes
  };

  React.useEffect(() => {
    const interval = setInterval(() => {
      // This update will cause App to re-render, creating new componentProps
      // PureComponent will then shallow compare these new props.
      setCount(c => c + 1);
    }, 2000);
    return () => clearInterval(interval);
  }, []);

  return (
    <div>
      <h1>Parent App Render Count: {count}</h1>
      <MyOptimizedComponent {...componentProps} />
    </div>
  );
}