Clean React Props

Common errors

• Warning: Received `myCustomProp` as a prop to a DOM element. If you intended to pass this as a custom attribute, etc.

  cause This is the core React warning that `clean-react-props` is designed to prevent. It occurs when a non-standard HTML attribute or a component-specific prop is passed directly to a native DOM element (e.g., a `div` or `span`) without being filtered.
  fix Wrap your DOM element's props with `cleanProps(this.props)` or `cleanSVGProps(this.props)` to automatically filter out unknown props. If `myCustomProp` is intended for a child component, ensure it's removed from the current component's props before spreading to the DOM element.

• TypeError: cleanProps is not a function

  cause This typically occurs if you attempt to import the default export `cleanProps` as a named export, or vice-versa for `cleanSVGProps` in an ESM context, or if using CommonJS `require` incorrectly.
  fix For `cleanProps` (default export), use `import cleanProps from 'clean-react-props';` or `const cleanProps = require('clean-react-props');`. For `cleanSVGProps` (named export), use `import { cleanSVGProps } from 'clean-react-props';` or `const { cleanSVGProps } = require('clean-react-props');`.

• Warning: Unknown event handler property `onMyCustomEvent`. Did you mean `onMycustomevent`?

  cause `clean-react-props` filters based on a list of known valid HTML/SVG attributes and event handlers. If you define a custom event handler that isn't on React's (and thus the library's) whitelist, it will be stripped, and React might still warn if the original prop object contains it.
  fix Ensure your custom event handlers are not passed directly to a native DOM element if `clean-react-props` is being used, or ensure they conform to standard React event naming conventions. If you need to pass a truly custom event handler to a custom component, extract it before applying `cleanProps` to a native DOM element.

Warnings

• gotcha React 16 and later versions introduced native support for custom attributes on HTML/SVG elements. This diminishes the primary use case of `clean-react-props` for developers who wish to pass custom `data-*` or other non-standard attributes directly to the DOM without warnings. The library remains useful for strict enforcement of standard attributes and explicit prop filtering.
  Fix: Evaluate if you still need `clean-react-props` if your main goal is to pass custom attributes. React 16+ handles `data-*` and other non-standard attributes gracefully. Use `clean-react-props` if you specifically want to strip *all* non-standard props or filter specific valid props.
• deprecated The package `braces` (a dependency of an indirect dependency) had a potential vulnerability (CVE-2018-1000006). This was addressed by `clean-react-props` updating its dependencies and specifically adding `braces@>=2.3.1` in `v0.3.2`.
  Fix: Upgrade to `clean-react-props@0.3.2` or later to ensure patched dependencies are used. Regularly run `npm audit` or `yarn audit`.
• gotcha When using `cleanProps` or `cleanSVGProps`, any props intended for child components or that have special handling within the current component (e.g., `className` for a styled component wrapper) must be explicitly excluded via the second argument. If not excluded, they will be filtered out.
  Fix: Always pass an array of prop names to the second argument of `cleanProps(props, ['propToExclude'])` for any props you wish to retain or handle manually after cleaning.

Install

• npm install clean-react-props npm
• yarn add clean-react-props yarn
• pnpm add clean-react-props pnpm

Imports

• cleanProps
  wrong:

  import { cleanProps } from 'clean-react-props';

  correct:

  import cleanProps from 'clean-react-props';

  cleanProps is the default export for cleaning HTML element props.
• cleanSVGProps
  wrong:

  import cleanSVGProps from 'clean-react-props';

  correct:

  import { cleanSVGProps } from 'clean-react-props';

  cleanSVGProps is a named export for cleaning SVG element props.
• All functions (CommonJS)
  wrong:

  import cleanProps from 'clean-react-props'; // CommonJS environments
  const cleanProps = require('clean-react-props').cleanProps;

  correct:

  const cleanProps = require('clean-react-props');
  const { cleanSVGProps } = require('clean-react-props');

  While primarily documented with ESM imports, CommonJS is supported. Ensure correct handling of default vs. named exports.

Quickstart

Demonstrates basic usage of `cleanProps` to filter props passed to a DOM element, including how to explicitly exclude certain valid props.

import cleanProps from 'clean-react-props';
import React from 'react';

// Example Component to demonstrate cleanProps usage
function MyComponent({ aProp, anotherProp, className, children, onClick, ...rest }) {
  // `aProp` and `anotherProp` are for internal component logic
  // `className` is explicitly excluded from the div to be handled by a child or styled component
  // `onClick` is a standard event handler, which cleanProps will retain
  // `rest` might contain unknown/custom props that cleanProps will filter

  return (
    <div {...cleanProps({ ...rest, aProp, anotherProp, className, onClick }, ['className'])}>
      <p>This div has clean props.</p>
      <ChildComponent aProp={aProp} />
      {children}
      <button onClick={onClick}>Click Me</button>
    </div>
  );
}

// Example usage in an app context
function App() {
  const handleButtonClick = () => console.log('Button clicked!');
  return (
    <MyComponent
      aProp="internal-value"
      anotherProp="another-internal"
      data-test-id="my-component-test" // Valid custom attribute in React 16+
      customAttribute="should-be-filtered" // Likely filtered by cleanProps
      onClick={handleButtonClick}
      style={{ border: '1px solid blue' }}
    >
      <span>Hello, world!</span>
    </MyComponent>
  );
}

// In a real application, you would render this using ReactDOM.render
// For demonstration, we'll log its representation.
console.log('App component configured with clean-react-props:', <App />);