README.md

React Integration

We're in the process of finding alternative, more sustainable ways to integrate better with React as React is also looking at ways to do the same. We've started another project at https://github.com/skatejs/val to try and make this more opt-in from consumers of web components and to open up the integration to libraries other than React.

Converts web components into React components so that you can use them as first class citizens in your React components.

• Web components become lexically scoped so you can use them as tag names in JSX.
• Listen for custom events triggered from web components declaratively using the standard on* syntax.
• Passes React props to web components as properties instead of attributes.
• Works with any web component library that uses a standard native custom element constructor, not just Skate or native web components.

Usage

Web components are converted to React components simply by passing them to the main react-integration function:

import reactify from 'skatejs-react-integration';

// Create your constructor.
class MyComponent extends HTMLElement {};

// Define your custom element.
window.customElements.define('my-component', MyComponent);

// Reactify it!
export default reactify(MyComponent);

Usage with SkateJS is pretty much the same, Skate just makes defining your custom element easier:

import reactify from 'skatejs-react-integration';

export default reactify(skate('my-component', {}));

Lexical scoping

When you convert a web component to a React component, it returns the React component. Therefore you can use it in your JSX just like any other React component.

const ReactComponent = reactify(WebComponent);
ReactDOM.render(<ReactComponent />, container);

Custom events

Out of the box, React only works with built-in events. By using this integration layer, you can listen for custom events on a web component.

// in MyComponent
var event = new Event('customevent');
elem.dispatchEvent(event);

// after reactified
<ReactComponent onCustomevent={handler} />

Now when customevent is emitted from the web component, your handler on ReactComponent will get triggered.

Web component properties

When you pass down props to the web component, instead of setting attributes like React normally does for DOM elements, it will set all props as properties on your web component. This is useful because you can now pass complex data to your web components.

// reactified component
<ReactComponent items={[ 'item1', 'item2' ]} callback={function() {}} />

// in MyComponent
<MyComponent items={elem.items} callback={elem.callback} />

Children

If your web component renders content to itself, make sure you're using Shadow DOM and that you render it to the shadow root. If you do this children and props get passed down as normal and React won't see your content in the shadow root.

ref

If you need access the the underlying DOM element, you can use the standard ref API. Beware that since you're dealing with a React Component, you'll need to use ReactDOM.findDOMNode:

import ReactDOM from 'react-dom';
const ReactComponent = reactify(class WebComponent extends HTMLElement {});

class MyComponent extends Component {
  constructor() {
    super();
    this.webComponent = null;
  }
  
  render() {
    return (
      <ReactComponent
        ref={reactComponent => { 
          this.webComponent = ReactDOM.findDOMNode(reactComponent);
        }}
      />
    );
  }
}

Injecting React and ReactDOM

By default, the React integration will import React and ReactDOM via peerDependencies. However, you can override this by passing your own versions:

import reactify from 'skatejs-react-integration';
import React from 'my-custom-react';
import ReactDOM from 'my-custom-react-dom';

class WebComponent extends HTMLElement {}
const ReactComponent = reactify(WebComponent, { React, ReactDOM });

Multiple React versions

The integration sets a peer-dependency on React so you know what it's compatible with. That said, you still need to be mindful that the version of React you provide to the integration layer is correct.