Node.prototype.contains() Polyfill

Common errors

• ReferenceError: Node is not defined

  cause Attempting to include or execute this browser-specific polyfill in a non-browser (e.g., Node.js server-side) environment.
  fix This package is explicitly for client-side browser environments. Ensure it is only included in your client-side bundles and excluded from server-side Node.js code. Use appropriate build tool configurations (e.g., Webpack targets, browser field in package.json) to achieve this separation.

• TypeError: undefined is not a function (evaluating 'element.contains(otherElement)')

  cause This error typically occurs when `Node.prototype.contains` is invoked on an object that is not a valid DOM `Node` or if the polyfill (or native support) has not been loaded/executed before the method call in a very old browser context. In modern browsers, this indicates `element` is not a `Node`.
  fix Verify that the `element` variable is indeed a DOM `Node` (e.g., obtained via `document.getElementById()`). If targeting extremely old browsers, ensure `import 'node-contains';` (or `require('node-contains');`) is executed at the very beginning of your application's entry point before any DOM manipulation code that relies on `contains`.

• Error: Module not found: Error: Can't resolve 'node-contains'

  cause The `node-contains` package has not been installed as a dependency in your project, or there is a typo in the import/require statement or package name.
  fix Install the package using your package manager: `npm install node-contains` or `yarn add node-contains`. Then, double-check the import or require statement for any spelling errors and ensure it matches the package name exactly.

Warnings

• breaking This polyfill is effectively obsolete. The `Node.prototype.contains()` method has been natively supported by all major web browsers since July 2015, making this package redundant for nearly all modern web development environments. Including it introduces unnecessary bundle size and may lead to subtle compatibility issues or conflicts if other polyfills or libraries also modify `Node.prototype`.
  Fix: Remove `node-contains` from your project's dependencies and codebase. Rely on the native browser implementation of `Node.prototype.contains()`.
• gotcha The package is unmaintained, with its last update in September 2014. Using unmaintained dependencies can expose projects to security vulnerabilities (e.g., supply chain attacks, unpatched bugs) as no further patches or updates are released for discovered issues.
  Fix: Migrate away from this package. If you absolutely need `Node.prototype.contains` in an ancient browser environment not covered by native support, consider a more modern, maintained polyfill or implement a minimal custom solution after careful consideration of risks.
• gotcha As a polyfill, `node-contains` modifies the global `Node.prototype`. While this is its intended function, in complex applications or environments where multiple polyfills or libraries might attempt to patch or define the same method, this could lead to unexpected behavior, overwrites, or conflicts, making debugging difficult.
  Fix: Audit your dependency tree for other polyfills or libraries that might target `Node.prototype.contains`. Prioritize native browser functionality, and if polyfills are strictly necessary, ensure they are well-maintained and don't create conflicts. Use conditional polyfilling techniques if possible.

Install

• npm install node-contains npm
• yarn add node-contains yarn
• pnpm add node-contains pnpm

Imports

• Node.prototype.contains
  wrong:

  import { contains } from 'node-contains';

  correct:

  import 'node-contains';

  This is a polyfill that directly modifies `Node.prototype`. There are no named exports; the import is for its side-effects.
• Node.prototype.contains (CommonJS)
  wrong:

  const contains = require('node-contains');

  correct:

  require('node-contains');

  For CommonJS environments, requiring the module applies the polyfill as a side-effect. It does not return an export.

Quickstart

This quickstart demonstrates how to include the `node-contains` polyfill and then use the `Node.prototype.contains()` method to check if a DOM node is a descendant of another.

import 'node-contains'; // Apply the polyfill (though likely unnecessary in modern browsers)

function checkContains() {
  const parentDiv = document.createElement('div');
  parentDiv.id = 'parent';
  const childSpan = document.createElement('span');
  childSpan.id = 'child';
  parentDiv.appendChild(childSpan);

  document.body.appendChild(parentDiv);

  // Using Node.prototype.contains() after the polyfill (or native support)
  const isContained = parentDiv.contains(childSpan);
  const selfContained = parentDiv.contains(parentDiv); // Node is considered to contain itself
  const notContained = document.body.contains(document.createElement('p'));

  console.log('Is childSpan contained in parentDiv?', isContained); // Expected: true
  console.log('Is parentDiv contained in itself?', selfContained); // Expected: true
  console.log('Is new P not contained in body?', notContained); // Expected: false (unless appended)

  document.body.removeChild(parentDiv);
}

// Run the check when the DOM is ready
if (document.readyState === 'loading') {
  document.addEventListener('DOMContentLoaded', checkContains);
} else {
  checkContains();
}