@actualwave/react-custom-element

• TODO lookup for possibility to add renderer with portal for easier develoment and testing, probably using slot to insert components but need to deal with context propagation

Adds support for independent modules wrapped in HTML Custom Elements. It provides a set of react hooks to establish communication through custom element container, so it is possible to pass data IN via custom element attributes and IN/OUT via events.

Web Components Using custom elements 3 Approaches to Integrate React with Custom Elements Web Components in React

Note: This does not isolate environments of running applications, all sub-applications running on one page will have access to same globals and it is possible for one application to interfere with others.

Installation

This package can be installed via its name @actualwave/react-custom-element. Using NPM

npm install @actualwave/react-custom-element

Or Yarn

yarn add @actualwave/react-custom-element

Integration

We have a react component which we want to use as an independent module, it is a normal react component.

const MyComponent = () => {
  return (
    <div>
      <h1>Hello World!</h1>
    </div>
  );
}

Instead of bootstrapping it via ReactDOM.render(), we register it as a custom element.

import { createCustomElement } from "@actualwave/react-custom-element";

createCustomElement({
  name: "my-component",
  render: () => <MyComponent />,
});

/**
 * For TypeScript you might need to add declaration fo custom element,
 * so it knows which attributes can be added to it.
 */

declare global {
  namespace JSX {
    interface IntrinsicElements {
      ["my-component"]: DetailedHTMLProps<
        HTMLAttributes<HTMLElement> & {
          onSomething: (event: Event) => void;
        },
        HTMLElement
      >;
    }
  }
}

createCustomElement({
  name: "my-component",
  render: () => <MyComponent />,
});

Then you have to import(or load in any other way) this component and use <my-component> HTML element.

import { useEffect, useRef } from "react";
import "./App.css";
import "./MyComponent";

function App() {
  return (
    <div className="app">
      <header className="App-header">
        <p>
          Edit <code>src/App.js</code> and save to reload.
        </p>
        <a
          className="App-link"
          href="https://reactjs.org"
          target="_blank"
          rel="noopener noreferrer"
        >
          Learn React
        </a>
      </header>
      <my-component></my-component>
    </div>
  );
}

export default App;

When custom HTML element is constructed, it will render MyComponent component as an independent React application.

Communication

Since modules integrated with custom elements are independent sub-applications, there are no way to communicate with them traditional React ways -- props or context. But you can communicate with sub-application by passing attributes, exposing methods or dispatching events.

Attributes

Attributes for custom element can be set or changed at any time and these changes could be captured by sub-application. Setting attribute

<my-component data-value="Something here"></my-component>

Reading attribute

import {
  createCustomElement,
  useContainerAttribute,
} from "@actualwave/react-custom-element";

const MyComponent = () => {
  const [readValue] = useContainerAttribute("data-value");

  return (
    <div>
      <h1>Hello World!</h1>
      <span>{readValue()}</span>
    </div>
  );
};

We can read any custom element attribute but listen for changes only for registered attributes. To register an attribute we have to provide it when registering custom element.

createCustomElement({
  name: "my-component",
  render: () => <MyComponent />,
  attributes: ["data-value", "id"],
});

Then we can use a change listener and it will be called whenever value of attribute is changed.

const MyComponent = () => {
  const [value, setValue] = useState("");

  const [readValue] = useContainerAttribute(
    "data-value",
    (name, oldValue, newValue) => setValue(newValue),
    []
  );

  useEffect(() => {
    setValue(readValue());
  }, [readValue]);

  return (
    <div>
      <h1>Hello World!</h1>
      <span>{value}</span>
    </div>
  );
};

And whenever attribute is changed, sub-application will be aware of that change.

import { useEffect, useRef } from "react";
import "./App.css";
import "./MyComponent";

function App() {
  const [value, setValue] = useState("");

  return (
    <div className="app">
      <my-component data-value={value}></my-component>
      <button onClick={() => updateValue("New attribute value")}>
        Change Value
      </button>
    </div>
  );
}

export default App;

This package also provides a way to read/update multiple attributes at once on a container HTML element

export const MyComponent = () => {
  const [values] = useContainerAttributes([
    "data-attr1",
    "data-attr2",
    "data-attr3",
  ]);

  return <div>{JSON.stringify(values)}</div>;
};

Methods

There are might be a case when you would want to expose custom methods on container element so they will be callable from outside. This can be done with useSetContainerCustomMethod() hook.

export const MyComponent = () => {
  const [value, setValue] = useState(0);

  useSetContainerCustomMethod("increment", () => setValue(value + 1));
  // useSetContainerCustomMethod("increment", () => setValue((val) => val++));

  return <div>Value: {value}</div>;
};

createCustomElement({
  name: "my-component",
  render: () => <MyComponent />,
});

When added to HTML tree, my-component tag will expose method increment() and you could call it like this

document.querySelector('my-component').increment();
// or
document.getElementsByTagName('my-component')[0].increment();
// or using any other way when you can get a reference of HTML element

There are no need to register attribute for such method via createCustomElement().

Events

Events allow to communicate both ways and pass non-serialized data by reference. React/JSX currently does not register custom events on custom elements. So, something like this may not work.

<my-component
  data-value="My value"
  onSomething={(event) => console.log("on something:", event)}
/>

One of the ways to make it work is to use CustomElementShim which manually assigns event listeners.

<CustomElementShim
  name="my-component"
  data-value="My value"
  onSomething={(event) => console.log("on something:", event)}
/>

Note: CustomElementShim is not aware of event phases and when using, for example, onClickCapture will not register click event for capture phase but will register clickCapture event for bubbling phase.

These events can be captured from within sub-application components using useContainerListener hook

useContainerListener(
  "something",
  (event) => console.log("Event:", event),
  false,
  []
);

To dispatch an event from sub-application on custom element use useContainerDispatch hook.

import { createCustomElement, useContainerDispatch } from "./custom-element";

const MyComponent = () => {
  const doSomething = useContainerDispatch("something");

  return (
    <div>
      <h1>Hello World!</h1>
      <button
        onClick={() => doSomething("There's something interesting here.")}
      >
        Do Something
      </button>
    </div>
  );
};