react-to-web-component

@r2wc/core is the core engine of the React to Web Component system. It converts React components into native Custom Elements (Web Components).

Key characteristics:

• The resulting custom element acts as a wrapper for the underlying React component.
• It allows React components to be used in any HTML-based environment (Vue, Svelte, Angular, Ember, etc.) without requiring the consumer to mount them through React.
• Note: This is an internal library. End-users should generally use renderers designed for this system, such as @r2wc/react-to-web-component, rather than using @r2wc/core directly.

The r2wc function creates a CustomElementConstructor equipped with custom getters, setters, and lifecycle methods.

Key Behaviors:

• Re-rendering: When a defined property is set on the custom element, the setter triggers a re-render of the underlying React component.
• Property Mapping: Enumerable properties and values on the custom element instance are passed directly as props to the React component.
• Optimization: The custom setter creates an enumerable getter/setter on the instance to store the value, preventing repeated hits to the proxy.
• Lazy Rendering: The React component is not rendered until the custom element is actually inserted into the DOM.

The library works by creating a CustomElementConstructor that manages the lifecycle and property synchronization between the Web Component and the React component.

Property Synchronization: When a property is set on the custom element, the internal setter:

1. Re-renders the React component inside the custom element with the new props.
2. Creates an enumerable getter/setter on the instance to cache the value and avoid unnecessary proxy hits in the future.

Data Flow:

• Props: Enumerable properties and values set on the custom element are passed directly to the React component as props.
• Rendering: The React component is not rendered until the custom element is actually inserted into the DOM.

You can use Web Components declaratively by adding their custom tag names to the HTML markup (e.g., via innerHTML). Once the element exists in the DOM, you can access it and update its properties to trigger updates in the component.

document.body.innerHTML = "<web-greeting></web-greeting>"

document.body.firstChild.name = "I do declare"

document.body.firstChild.innerHTML //-> "<h1>Hello, I do declare</h1>"

When using a Web Component generated by reactToWebComponent, you can pass data via HTML attributes. To ensure compatibility with React props, convert camelCase prop names to kebab-case in your HTML.

For example, if your React component has a colorMode prop, use the color-mode attribute in the HTML tag.

<!-- Using kebab-case for attributes to map to camelCase React props -->
<web-greeting
  name="Sven"
  description="How do you do?"
  color-mode="dark"
  button-variant="contained"
></web-greeting>

You can instantiate and manipulate Web Components using standard DOM APIs. Create the element using document.createElement, set its properties directly, and then append it to the document. Changes to properties will reflect in the component's internal rendering.

const webGreeting = document.createElement("web-greeting")
webGreeting.name = "Justin"

document.body.append(webGreeting)

webGreeting.innerHTML //-> "<h1>Hello, Justin</h1>"

Install the package via npm to begin converting React components into custom elements.

Note: The latest version of this package requires React 18. If you are using React 16 or 17, you must use version 1.

npm install @r2wc/react-to-web-component

To convert a React component, import r2wc and pass your component to it. The function returns a constructor that you can then register using the standard customElements.define API.

By default, r2wc only passes properties to the underlying React component. It does not automatically map HTML attributes to React props unless they are explicitly defined in the configuration.

import r2wc from "@r2wc/react-to-web-component"

const Greeting = () => {
  return <h1>Hello, World!</h1>
}

const WebGreeting = r2wc(Greeting)

customElements.define("web-greeting", WebGreeting)

To allow your custom element to respond to HTML attributes (e.g., <web-greeting name="Justin"></web-greeting>), you must provide a configuration object as the second argument to r2wc. This object must include a props mapping that defines the expected types for your component's props.

const Greeting = ({ name }) => {
  return <h1>Hello, {name}!</h1>
}

const WebGreeting = r2wc(Greeting, {
  props: {
    name: "string",
  },
})

customElements.define("web-greeting", WebGreeting)

Use reactToWebComponent(ReactComponent, React, ReactDOM, options) to create a class inheriting from HTMLElement. This class can be passed to customElements.define or extended.

Parameters:

• ReactComponent: The React component to convert.
• React: The React library.
• ReactDOM: The ReactDOM library.
• options: Configuration object (see Typed Props for details).

Options:

• shadow: `