Custom Attributes: When They Work and When They're Stripped
What you'll learn: When React passes your custom HTML attributes through to the DOM versus when it silently ignores them.
The Core Rule
React has historically been selective about which attributes it renders to the DOM. While standard HTML attributes (id, class, src) and the exceptions you've learned (data-*, aria-*) always pass through, React used to strip unknown custom attributes entirely.
Modern React (16.2+) changed this: Custom attributes now pass through to the DOM, but with an important caveat—they must be lowercase.
What Works
// ✅ These render to the DOM
<div custom="value" /> // lowercase custom attribute
<div data-test-id="login" /> // data-* (you already know this)
<div aria-label="Close" /> // aria-* (you already know this)
What Gets Stripped
// ❌ These are silently ignored
<div customProp="value" /> // camelCase (React assumes it's a component prop)
<div CustomAttr="value" /> // PascalCase (same reason)
<div onCustomEvent={fn} /> // looks like an event handler
Why This Matters
Think of React as a bouncer checking IDs at a club. Lowercase custom attributes get the nod—they look like standard HTML. But camelCase screams "JavaScript prop," so React assumes you meant it for the component, not the DOM, and strips it out.
Use case: Web components, testing selectors, or progressive enhancement scripts often need custom attributes. Now you know how to make them render.
Key Takeaway: Custom attributes in JSX pass through to the DOM only if they're all lowercase—camelCase or PascalCase attributes are treated as component props and stripped from the final HTML.