web-components-react-bindings
TypeScript icon, indicating that this package has built-in type declarations

1.2.1 • Public • Published

web-components-react-bindings

What?

web-components-react-bindings allows binding non-string props (like numbers, objects, arrays or functions) to web-components using React

Why?

React doesn't play well with web-components natively, so a bindings layer is necessary for correctly passing-down properties and binding to events.

You can check more info about this on this URL: https://custom-elements-everywhere.com/

How?

web-components-react-bindings uses Proxy and react-hooks under the hood:

  • react-hooks: in order to set non-string properties and to bind to events we need to get a reference to the component's instance; for this purpose we are using useRef and creating a new hook called useBindings that will receive the props and pass down to web-components accordingly.
  • Proxy: whenever you call the proxy it will return a function that is used as a HOC to connect your React application with native web-components, using useBindings described above.

Simple example

Imagine ther is a custom-button web-component registered, and it accepts a label property and emmits an buttonClick event; you will instantiate the component into your React app using the following snippet:

import WC from 'web-components-react-bindings'

const App = () => {

  function handleClick() {
    console.log('clicked!')
  }

  return (
    <p>This is my button: </p>
    <WC.CustomButton label={'My button'} onButtonClick={handleClick} />
  )
}

export default App

WC in the example above is the proxy. When you are accesing one of it's properties like WC.CustomButton it is returning a constructor function that will instantiate your <custom-button> web-component and implement useBindings() with the props you are passing to <WC.CustomButton />

Note that for binding events the property name should begin with on; for the moment this convention is necessary for this to work properly.

Using Namespaces

If all your web-components share the same prefix/namespace (e.g. my-components-) then you can create a namespace to intantiate those component easily.

First, create a file to create and export your namespace (e.g. myComponents.js):

import { createNamespace } from 'web-components-react-bindings'

export default createNamespace('my-components')

Then you can use it in your React components:

import MC from './myComponents'

const App = () => {

  function handleClick() {
    console.log('clicked!')
  }

  return (
    <p>This is my button: </p>
    <MC.Button label={'My button'} onButtonClick={handleClick} />
  )
}

export default App

Note that the example is very similar, but now you can avoid adding MyComponents for each of your components name.

License

MIT

Dependencies (0)

    Dev Dependencies (18)

    Package Sidebar

    Install

    npm i web-components-react-bindings

    Weekly Downloads

    1

    Version

    1.2.1

    License

    MIT

    Unpacked Size

    22.5 kB

    Total Files

    12

    Last publish

    Collaborators

    • agallardo