Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
createComponent
✓ import { createComponent } from 'ce-la-react';
✗ const { createComponent } = require('ce-la-react');
The library primarily uses ES module syntax. While CJS might work via transpilation, direct ESM imports are recommended for modern React projects.
EventName
✓ import type { EventName } from 'ce-la-react';
Used for type casting custom event names in TypeScript to provide strong typing for event callbacks. Always import as a type.
React
✓ import * as React from 'react';
✗ import React from 'react';
Ensure you import React correctly based on your project's `tsconfig.json` (e.g., 'preserve' or 'react-jsx') and React version. `import * as React` is generally safe.
This code demonstrates how to create a React component wrapper for a custom element using `createComponent`. It includes a minimal, self-contained custom element definition and shows how to pass props from React to the custom element and listen for custom events with type-safety using `EventName`.
import * as React from 'react';
import { createComponent } from 'ce-la-react';
import type { EventName } from 'ce-la-react';
// Define a simple custom element for demonstration purposes
class MyToggleElement extends HTMLElement {
static observedAttributes = ['active'];
private _active: boolean = false;
constructor() {
super();
this.attachShadow({ mode: 'open' });
this.shadowRoot!.innerHTML = `<style>
:host { display: inline-block; padding: 8px; border: 1px solid #ccc; border-radius: 4px; }
button { padding: 8px 12px; cursor: pointer; background: #007bff; color: white; border: none; border-radius: 3px; }
button.active { background: #28a745; }
</style>
<button>${this._active ? 'Active' : 'Inactive'}</button>`;
this.shadowRoot!.querySelector('button')!.onclick = () => {
this.active = !this.active;
};
}
set active(value: boolean) {
if (this._active === value) return;
this._active = value;
if (value) {
this.setAttribute('active', '');
} else {
this.removeAttribute('active');
}
this.updateButtonText();
this.dispatchEvent(new CustomEvent('toggle', { detail: { active: value }, bubbles: true, composed: true }));
}
get active(): boolean {
return this._active;
}
attributeChangedCallback(name: string, oldValue: string, newValue: string) {
if (name === 'active') {
this.active = newValue !== null;
}
}
private updateButtonText() {
const button = this.shadowRoot!.querySelector('button');
if (button) {
button.textContent = this._active ? 'Active' : 'Inactive';
button.classList.toggle('active', this._active);
}
}
}
customElements.define('my-toggle-element', MyToggleElement);
interface ToggleEventDetail { active: boolean; }
// Create the React component wrapper
export const MyToggleComponent = createComponent({
tagName: 'my-toggle-element',
elementClass: MyToggleElement,
react: React,
events: {
onToggle: 'toggle' as EventName<CustomEvent<ToggleEventDetail>>
},
});
// Example React usage
export function App() {
const [isActive, setIsActive] = React.useState(false);
return (
<div>
<h1>ce-la-react Custom Element Demo</h1>
<p>React State: {isActive ? 'ON' : 'OFF'}</p>
<MyToggleComponent
active={isActive}
onToggle={(e: CustomEvent<ToggleEventDetail>) => {
console.log('Custom event received:', e.detail.active);
setIsActive(e.detail.active);
}}
/>
<p>Click the custom element button to toggle its state and see React update.</p>
</div>
);
}
// To run this in a real app, you would typically render `App`:
// import { createRoot } from 'react-dom/client';
// const container = document.getElementById('root');
// if (container) {
// const root = createRoot(container);
// root.render(<App />);
// }
Errors
Common errors & fixes
ReferenceError: HTMLElement is not defined
This error typically occurs during server-side rendering (SSR) if the Node.js environment does not have a global `HTMLElement` available, which is a browser-specific API.
fixEnsure that your SSR setup either mocks `HTMLElement` (and other DOM APIs) or that the custom element definition is guarded to only run in a browser environment, or use a tool that provides a browser-like environment for SSR.
TypeError: Cannot set properties of undefined (setting 'active') or elementClass.prototype undefined
This specific error ('elementClass.prototype undefined error with corejs polyfill') was a known bug related to interactions with `core-js` polyfills, especially in older versions.
fixUpgrade to `ce-la-react` version 0.3.1 or newer. If the issue persists, review your `core-js` polyfill configuration to ensure it's compatible with modern browser APIs and custom element specifications.
Type 'CustomEvent<MyDetail>' is not assignable to type 'Event'
This TypeScript error occurs when a custom event callback expects a specific `CustomEvent` type (e.g., `CustomEvent<MyDetail>`) but the `events` map in `createComponent` was not correctly type-casted with `EventName<CustomEvent<MyDetail>>`, causing the callback parameter to default to the generic `Event` type.
fixIn your `createComponent` configuration, explicitly type cast your custom event names. For example, `events: { onMyEvent: 'my-event' as EventName<CustomEvent<MyDetail>> }`. Audit
Dependencies
reactrequiredRequired as a peer dependency for creating and using React components and their APIs.