Create framework agnostic components that are truly reusable and interoperable with all the benefits of the React ecosystem – using the HTML5 custom elements API to extend HTML's vocabulary.

• npm:

  npm install react-standalone --save

Table of Contents

• Getting Started
• Handling Props
  • Specifying a Schema
• Component Events
  • Passing JSON Structure
• Element Methods
• Extending Elements
• Browser Support

Getting Started

Take a look at the

mars-weather

mars-weather

component

osom

import { createModule } from 'standalone';
import schema from './schema';
import component from './component';

export default createModule('mars-weather', { schema, component });

Once you have created your package, a custom element will be created with the supplied

tagName

componentWillUnmount

As the

mars-weather

Bonus: Use Keo with shadow boundaries for a true Polymer-esque feel.

Handling Props

By specifying attributes on the custom element, the values of the attributes are passed into your component as props – any changes to the

state

props

In the

mars-weather

getDefaultProps

unit

data

data-unit

In the above case, the

data-unit

unit

Standalone

data-

this.props.unit

Specifying a Schema

As all HTML attributes are

string

Standalone

string

osom

export default {
    unit: {
        type: String,
        default: 'F'
    }
};

Once you have configured the schema to use for your component, you can happily setup the usual React

propTypes

Component Events

Using Custom Events you can easily set-up a communication channel between your components and the outside world.

// Instantiate `CustomEvent` and then specify the name of the event, followed
// by the payload which will be passed to your listener function.
const event = new CustomEvent('migrate-planets', {
    bubbles: true,
    detail: {
        planet: 'Saturn'
    }
});

findDOMNode(this).dispatchEvent(event);

It's crucial that you emit the event as

bubbles: true

findDOMNode(this)

mars-weather

mars-weather

findDOMNode(this).parentNode

Within your component you emit the event —

CustomEvent

dispatchEvent

mars-weather

addEventListener

const node = document.querySelector('mars-weather');

node.addEventListener('migrate-planets', event => {
// Update the `data-planet` attribute to reflect the newly migrated planet
// which will cause the component to re-render with the update prop.
node.setAttribute('data-planet', event.detail.planet);
});

Passing JSON Structure

As invoking

setAttribute

setAttribute

By defining a schema you can specify an attribute that will be parsed as JSON.

export default {
    payload: {
        type: JSON.parse
    }
}

Attaching a JSON string to your element's

data-payload

JSON.parse

this.props.payload

propTypes

PropTypes.shape

Element Methods

All

Standalone

HTMLElement.prototype

mars-weather

const getWeather = function() {
    const weather = this.component.state.weather.atmoOpacity.toLowerCase();
    return `The current weather on Mars is ${weather}!`;
};

// ...
document.querySelector('mars-weather').getWeather();

When a component has been appended to the DOM it will update its

HTMLElement

getPrototypeOf(this).component

props

state

It's worth noting that

this.component

Extending Elements

With the Custom Elements API it is possible to extend existing elements – using the

is

Standalone

// Creates a `mars-weather` element.
export default createModule('mars-weather', { schema, methods, component });

// Creates a input[is="mars-weather"] element.
export default createModule('input/mars-weather', { schema, methods, component });

It's worth noting that when you extend a known element, your element will extend its prototype – in the case above the

mars-weather

input

HTMLInputElement

Browser Support

• Chrome >= v33
• Opera >= v20
• *IE >= 11
• *Safari >= 7
• *Firefox

* Requires the excellent webcomponents-lite.js polyfill (13K gzipped)