@emotion/is-prop-valid

@emotion/is-prop-valid is a high-performance TypeScript utility function that determines whether a given prop name is valid for HTML and SVG elements. It uses memoization for optimal performance and includes comprehensive validation patterns for React props, HTML attributes, SVG properties, and event handlers.

Package Information

• Package Name: @emotion/is-prop-valid
• Package Type: npm
• Language: TypeScript
• Installation: npm install @emotion/is-prop-valid

Core Imports

import isPropValid from "@emotion/is-prop-valid";

For CommonJS:

const isPropValid = require("@emotion/is-prop-valid");

Basic Usage

import isPropValid from "@emotion/is-prop-valid";

// Valid HTML attributes
isPropValid("className"); // true
isPropValid("href"); // true
isPropValid("style"); // true

// Valid event handlers
isPropValid("onClick"); // true
isPropValid("onSubmit"); // true
isPropValid("onMouseOver"); // true

// Valid data and aria attributes
isPropValid("data-testid"); // true
isPropValid("aria-label"); // true

// Valid SVG attributes
isPropValid("viewBox"); // true
isPropValid("strokeWidth"); // true

// Invalid custom props
isPropValid("customProp"); // false
isPropValid("mySpecialAttribute"); // false

Capabilities

Prop Validation

Validates whether a prop name is acceptable for HTML and SVG elements, preventing invalid attributes from being passed to DOM elements.

declare function isPropValid(prop: string): boolean;
export default isPropValid;

The function validates props against two main criteria:

1. HTML/SVG Attributes: Tests against a comprehensive regex pattern that includes:

   • React-specific props: children, dangerouslySetInnerHTML, key, ref
   • Standard HTML attributes: className, href, style, id, title, etc.
   • SVG properties: viewBox, fill, stroke, d, cx, cy, etc.
   • Data/Aria attributes: data-*, aria-*, and x-* prefixed attributes
   • RDFa and other non-standard properties

2. Event Handlers: Direct character code check for props starting with "on" followed by an uppercase letter

The function uses memoization for performance optimization.

Common Usage Patterns:

import isPropValid from "@emotion/is-prop-valid";
import styled from "@emotion/styled";

// Most common usage: shouldForwardProp in styled components
const StyledDiv = styled.div.withConfig({
  shouldForwardProp: (prop) => isPropValid(prop),
})`
  color: ${props => props.color};
`;

// Filter out custom props before passing to DOM
function filterValidProps(props: Record<string, any>) {
  return Object.keys(props).reduce((validProps, key) => {
    if (isPropValid(key)) {
      validProps[key] = props[key];
    }
    return validProps;
  }, {} as Record<string, any>);
}

// Usage with conditional prop forwarding
const ConditionalForwardProp = styled('div', {
  shouldForwardProp: prop => prop !== 'customProp' && isPropValid(prop)
})`
  background: blue;
`;

Comprehensive Property Coverage

The validation covers all major categories of valid HTML and SVG properties:

React Props:

• Core: children, dangerouslySetInnerHTML, key, ref
• Form: defaultValue, defaultChecked, innerHTML
• Warnings: suppressContentEditableWarning, suppressHydrationWarning
• Focus: autoFocus
• Deprecated: valueLink

HTML Attributes:

• Common: className, id, style, title, lang, dir, role
• Form: action, method, encType, target, formAction, formNoValidate
• Media: src, href, alt, width, height, controls, poster, preload
• Interactive: draggable, contentEditable, tabIndex, hidden, disabled
• Security: nonce, integrity, crossOrigin
• Modern: loading, fetchPriority, enterKeyHint, inputMode

SVG Properties:

• Geometry: x, y, width, height, cx, cy, r, d
• Styling: fill, stroke, strokeWidth, opacity, transform
• Text: fontSize, fontFamily, textAnchor, dominantBaseline
• Filters: filter, clipPath, mask, gradientTransform

Event Handlers: All standard DOM events starting with "on" followed by uppercase letter:

• Mouse: onMouseDown, onMouseUp, onMouseOver, onMouseOut
• Keyboard: onKeyDown, onKeyUp, onKeyPress
• Form: onSubmit, onChange, onFocus, onBlur
• Touch: onTouchStart, onTouchMove, onTouchEnd

Data/Aria Attributes:

• Data attributes: data-* (e.g., data-testid, data-value)
• ARIA attributes: aria-* (e.g., aria-label, aria-hidden)
• Custom namespaced: x-* (e.g., x-custom-attribute)

Additional Supported Attributes:

• Preact compatibility: for, class, autofocus
• RDFa properties: about, datatype, property, resource, typeof
• Microdata: itemProp, itemScope, itemType, itemID, itemRef