Skip to content

A thin wrapper around an arbitrary custom HTML element to mitigate the gaps in :atom: React versions until 19.x

Notifications You must be signed in to change notification settings

Vonage/vivid-react-wrapper

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

64 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

This utility library creates a React component that serves as a thin wrap around an arbitrary custom element. It is used to mitigate the gaps present in React versions until 19.x

  • Relay custom events that are not natively supported to callback
  • Handles properties as well as attributes on a custom element

Rationale

At present(early 2023) we as a community of React users are still in between of two points in time:

  • React 18.2 (June 14, 2022)
  • React 19 (?unknown release date?) Native support of Web Components promised to be delivered near version 19

This means we can't use Web Components with the React happily together because

and somwhere in the future this might be better

Alternative solutions

Articles on topic

Getting Started

To install react wrapper in your project, run:

npm i @vonage/vivid-react-wrapper

In order to use it in your code, just import the wrapper function into your project, then invoke it with the configuration that's relevant to the element you're wrapping.

import React from "react";
import ReactDOM from "react-dom";
import "@material/mwc-textarea";
import wrapper from "@vonage/vivid-react-wrapper";

const MwcTextarea = wrapper('mwc-textarea',  {
    events: ["change"],
    attributes: ["disabled"]
});

Then you can use the generated component as you would any other React component. Supplying callbacks for events and attribute values as properties:

ReactDOM.render(
    <MwcTextarea
      disabled="true"
      onClick={ console.log }
      onChange={ console.log }
      ref={ console.log }
      value="hello">
    </MwcTextarea>,
    document.body
);

The wrapper function takes two arguments

  • The name of the custom element to wrap
  • An options object containing two fields:
    • events: An array of events that the wrapper should handle. For instance, the "change" event isn't handled by React automatically, so we'd want to add "onChange" to the list of events. To consume these events, all you need is to assign a callback property "onChange" to the React element instance.
    • attributes: An array of attributes that the wrapper should relay to the element. Some element attributes are assigned/removed instead of set value to (as in the case of the "disabled" attribute).

All properties that have not been explicitly configured to be handled by the wrapper, including "ref" will be transferred to the element natively by React.

Extended Configuration

import "@material/mwc-textarea";
import wrapper, { attributeSetterValue, attributeSetterToggle } from "@vonage/vivid-react-wrapper";

const MwcTextarea = wrapper('mwc-textarea',  {
    events: [
        { name: "change", propName: 'onChange', transform: (e) => e.target.value }
    ],
    attributes: [
        { name: "disabled", setter: attributeSetterToggle },
        { name: "placeholder", setter: attributeSetterValue }
    ]
});

Releasing new version

  • Bump the version in package.json commit & push the change to the master
  • Run Pipeline workflow manually