npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@philipoliver/react-to-html-element

v1.5.1

Published

Converts React Components to HTML Element (also known as Web Component, Custom Element)

Downloads

14

Readme

Node.js CI made-with-javascript Maintenance GitHub latest commit Npm package version

react-to-html-element

react-to-html-element turns a React component into a Web Component. To see a practical case of how to use in your existing applications, see the Example section (after reading the documentation of course 😊)

Sections :

Usages

The React component must declare its properties and their types in the static componentProps attribute (or prop-types), as in the example below.

import React from 'react';
import PropTypes from "prop-types"; // add this line, if you want to declare with PropTypes

const MyButton = ({ someBool, someNumber, someString, someObject, someArray, someSlot, children }) => {
    // do anything here with properties
    return (
        <button disabled={someBool} data-identifier={someNumber} data-extra={someString}>
            {children}
        </button>
    );
}

// Declare as below without using prop-types
MyButton.componentProps = {
    someBool: Boolean,
    someNumber: Number,
    someString: String,
    someObject: Object,
    someArray: Array,
    someSlot: Node,
    someFunc: Function,
}

// Or else using prop-types 
MyButton.propTypes = {
    someBool: PropTypes.bool,
    someNumber: PropTypes.number,
    someString: PropTypes.string,
    someObject: PropTypes.object,
    someArray: PropTypes.array,
    someSlot: PropTypes.node,
    someFunc: PropTypes.func,
}

export default MyButton;

Then after declaring the properties, you must register your React components as WebComponent, like this :

import React from 'react';
import * as ReactDOM from "react-dom/client";
import { register } from "react-to-html-element";
import MyButton from "./src/MyButton";

register(MyButton, 'my-button', React, ReactDOM);

It's up to you to find the ideal location to register your components and then build them, export them, publish them etc... (you can imagine publishing them to a CDN, npm...)

Use of the web component created :

<html>
<body>
   <my-button some-bool="true" some-number="45" some-string="Hello" some-object='{"name": "Will"}' some-array="[1, 2, 3]">
       It's a Button
   </my-button>
</body>
</html>

Extend the WebComponent

You can create an extension of the WebComponent to suit your needs, by adding {returnElement: true} as options. and then it's up to you to define the WebComponent in the DOM.

// ...
import { register } from "react-to-html-element";
import MyButton from "./src/MyButton";

class WCButton extends register(MyButton, null, React, ReactDOM, {returnElement: true})
{
    constructor(props) {
        super(props);
    }

    connectedCallback() {
        super.connectedCallback();
        console.log('Component connected to the DOM');
    }
}

customElements.define('my-button', WCButton); // define your component to the DOM

Slots

It is possible to add slots in your custom elements. They will be added to the React component props. Here is an example of how to do it :

<my-dialog>
    <slot name="header">...</slot>
    <slot name="body">...</slot>
    <slot name="footer">...</slot>
</my-dialog>
<!-- Or else you can do as below -->
<my-dialog>
    <h3 slot="header">...</h3>
    <p slot="body">...</p>
    <div slot="footer">...</div>
</my-dialog>

In your React component :

import React from 'react';

const MyDialog = ({ header, body, footer }) => {
    return (
        <div>
            <div>{header}</div>
            <div>{body}</div>
            <div>{footer}</div>
        </div>
    );
}

MyDialog.componentProps = {
    header: Node,
    body: Node,
    footer: Node,
}

export default MyDialog;

rootElement

This is a property injected into all registered React components, which corresponds to the instance of the WebComponent rootElement instanceof HTMLElement. For example, it can be used to trigger or intercept JavaScript events :

function MyButton({ someString, rootElement }) {
    const buttonClicked = () => {
        const event = new CustomEvent('btnClicked', { detail: {identifier: 45}})
        rootElement.dispatchEvent(event)
    }

    return (
        <button onClick={buttonClicked}>{someString}</button>
    );
}

How to listen event :

<html>
<body>
    <my-button some-string="Hello"></my-button>

    <script>
        document.addEventListener('DOMContentLoaded', function () {
            let button = document.querySelector('my-button');

            button.addEventListener('btnClicked', function (e) {
                console.log('identifier clicked : ' + e.detail.identifier);
            });
        })
    </script>
</body>
</html>

Usage of Ref

Let's take the example of a React component that has a function that can be called from the DOM, for example validating that an input is valid and returning true if it is or otherwise false.

import React, {forwardRef, useImperativeHandle} from 'react';

const MyInput = forwardRef(({placeholder}, ref) => {

    useImperativeHandle(ref, () => ({
        isValid: () => {
            // put logic here
            return true; // or return false
        }
    }));

    return <input placeholder={placeholder} type="text"/>;
});

MyInput.componentProps = {
    placeholder: String,
}

export default MyInput;

There are 3 important points :

  • The component must be wrapped with forwardRef hook.
  • Add as second parameter the variable ref, example (props, ref) or ({props1, prop2}, ref).
  • Use the useImperativeHandle hook to expose functions outside the component.

After doing that, now here is an example of how to register the component :

// ...
import { register } from "react-to-html-element";
import MyInput from "./src/MyInput";

class WCInput extends register(MyInput, null, React, ReactDOM, {returnElement: true, hasReactRef: true})
{
    constructor(props) {
        super(props);
    }
    
    async isInputValidAsync() {
        let ref = await this.getAsyncReactRef();
        return ref.isValid(); // call the React component function
    }
    
    isInputValid() { // or you can do it like this
        return this.getReactRef().isValid(); // call the React component function
    }
}

customElements.define('my-input', WCInput); // define your component to the DOM

// call function like this :
let input = document.querySelector('my-input');
let isValid = input.isInputValid();

// or with async (inside async function) :
let input = document.querySelector('my-input');
let isValid = await input.isInputValidAsync();

The asynchronous should be used in case the WebComponent may not be ready in the DOM yet, to avoid having undefined

Below is another example of using the ref to sibling the input inside a React component and toggle focus on it :

// ...
const MyInput = forwardRef((props, ref) => {
    return <input ref={ref} type="text"/>;
});

class WCInput extends register(MyInput, null, React, ReactDOM, {returnElement: true, hasReactRef: true})
{
    // ...
    focusInput() {
        this.getReactRef().focus(); // call focus method of input
    }
}

// clicking on a button activates the focus on the input :
let input = document.querySelector('my-input');

button.addEventListener('click', function () {
    input.focusInput();
});

Update attributes

After the component has been rendered, you can update the attributes, and the component will be re-rendered :

let button = document.querySelector('my-button');
button.someString = "Good bye";
// or
button.setAttribute("some-string", "Good bye");

button.someArray = [1, 2, 3];
button.someBool = true;
// ...

Function attributes need a reference to declared function:


<my-button handle-click="sayHello"></my-button>
<my-button handle-click="Greeting.sayHello"></my-button>

<script>
  function sayHello() { ... }
  
  class Greeting {
    static sayHello() { ... }
  }
</script>

// and retrieve the function inside you React component (props.handleClick)

API

The register function has as parameters :

  • ReactComponent The React component that needs to be turned into a WebComponent.
  • name The name of the desired WebComponent tag.
  • React The version of React that was used to create the components.
  • ReactDOM The version of ReactDOM that was used to create the components.
  • options : object of options default = {modeShadow: false, returnElement: false, hasReactRef: false, className: "html-element"}
    • modeShadow Create components in shadow mode.
    • returnElement The function returns the WebComponent to be overridden
    • hasReactRef The React component will have ref functionality enabled
    • className CSS class that will be added to the HTML container

Conflicts to avoid

There are points to know to allow the proper functioning of this package:

  • If you rewrite the connectedCallback method of the returned component always call the parent by doing: super.connectedCallback();
  • The children, rootElement and ref properties do not need to be declared, they will be automatically injected into the component.
  • Do not use these properties in your components: custom custom-parent custom-state
  • If you encounter a problem of FOUC, flickering, glitch (visual problem), add these CSS rules:
[custom]:not([custom-state="hydrated"]) {
    visibility: hidden;
}

:not(:defined) {
    visibility: hidden;
}

Example

See example on codesandbox: https://codesandbox.io/s/react-to-html-element-397stp

To go further, you can imagine for example having a component library in React, which you could export to all your applications, here is an example among hundreds that you could imagine.

Start by creating a React app using create-react-app. You can base yourself on the example in codesandbox, it's exactly the same things except that we will talk about the build and include in your applications.

npx create-react-app my-web-components
cd my-web-components

You can remove all the files created by create-react-app inside the src folder, it's up to you to create your tree (structure). You can imagine something like this :

my-web-components/
└── src/
    ├── components/
    │   ├── MyButton.jsx
    │   ├── MyInput.jsx
    │   └── ...
    ├── layouts/
    │   ├── Header.jsx
    │   ├── Footer.jsx
    │   └── ...
    ├── style/
    │   ├── index.css
    │   ├── my-button.css
    │   ├── my-input.css
    │   └── ...
    └── index.js
package.json

Install react-to-html-element in your project:

npm install react-to-html-element

Then it's up to you, from the README and the examples in codesandbox, create your components and register them in the src/index.js file!

Then we will use the react-scripts build command which is already installed with create-react-app, being at the root of your project and doing this command :

npm run build

After the command completes, there is a build folder created in the root. Inside are the compiled and minified files, for example :

build/static/js/main.e77e15c3.js
build/static/css/main.2e73bf20.css    👈 and if you included css

These files contain your WebComponents ready to be used anywhere! How to use them :

<!doctype html>
<html>
<head>
    <link rel="stylesheet" href="build/static/css/main.2e73bf20.css">
</head>
<body>
    <my-button>Button</my-button>

    <script src="build/static/js/main.e77e15c3.js"></script> <-- put the JS build here
</body>
</html>