api.md

Remount API

import { define } from 'remount'

• define()
  • Multiple elements
  • Passing options
  • Per-element options
  • Named attributes
  • props-json
  • Shadow DOM
  • Options
  • Custom adapters
  • Fixing React events
• getStrategy()

define()

define({ [string]: React.Component, ... }, options?: Options)

Defines custom elements.

define({
  'x-my-element': MyComponent
})

Multiple elements

You can pass as many elements to define() as you need.

define({
  'x-my-element': MyComponent,
  'x-other-element': OtherComponent
})

Passing options

You can pass options as the second parameter of define(). This example below will apply the attributes: ['name'] option to the 2 components defined:

define({
  'x-my-element': MyComponent,
  'x-other-element': OtherComponent
}, {
  attributes: ['name']
})

Per-element options

Alternatively, you can also pass options per component using this syntax:

define({
  'x-checkbox': {
    component: Checkbox,
    attributes: ['value', 'label']
  }
  'x-tooltip': {
    component: Tooltip,
    attributes: ['title', 'body']
  }
})

Named attributes

You have to pass attributes that you want to listen to, see above. All attributes not specified in define() will be ignored.

Remount relies on the Custom Elements HTML API, so all limitations of the Custom Elements API apply. Keep these in mind:

• Attribute names are case insensitive.

• Values can only be expressed as strings.

props-json

All elements allow for the props-json attribute.

<x-my-element props-json='{"color":"red"}'></x-my-element>

While being more verbose than named attributes, it lets you have props without the limitations of named attributes:

• You can use non-string values like numbers or booleans. (named attributes only support strings.)

• You can use mixedCase property names. (named attributes are case insensitive.)

If a props-json property exists, all other named attributes will be ignored.

Shadow DOM

Remount doesn't use Shadow DOM by default. To enable it, pass the shadow: true option.

Shadow DOM mode is only available when Remount is using Custom Elements (check getStrategy() below).

The Shadow DOM API should be available anywhere custom elements are, but keep in mind that your React elements will be "hidden" from JavaScript. Depending on your situation, this may be a good or bad thing. For better compatibility with older browsers, leave this option off, since older browsers don't support the Shadow DOM API.

define({
  'x-component': MyComponent
}, {
  shadow: true
})

Fixing React events

Shadow DOM and React events don't play nicely together at the moment. This can be fixed using react-shadow-dom-retarget-events. To use this:

define({
  'x-component': MyComponent
}, {
  shadow: true,
  retarget: true
})

NOTE: When using this feature event.nativeEvent is no longer present in React event handlers.

Options

define() accepts these options:

• component - The React component to bind to. This is only required if you use the per-element options syntax.

• attributes - The attributes to listen to (see Named attributes).

• quiet - If true, warnings will be supressed.

• shadow - If true, uses shadow DOM. Only available for Custom Elements mode. (experimental)

• adapter - Provides a custom adapter

Custom adapters

You can specify custom adapters to integrate Remount with other non-React frameworks.

const ElmAdapter = {
  mount({ component }, mountPoint, props) {
    // This function will be called on the first appearance of the custom
    // element.
    component.embed(mountPoint, props)
  },
  update({ component }, mountPoint, props) {
    // This function will be called on any subsequent updates afterwards (ie,
    // if attributes were changed).
  },
  unmount({ component }, mountPoint) {
    // This function will be called when a custom element is removed from the
    // DOM (eg, `parent.removeChild()`).
  }
}

define({
  'x-elm-tooltip': Elm.Tooltip
}, {
  adapter: ElmAdapter
})

getStrategy()

Returns the default strategy that will be used.

import { getStrategy } from 'remount'

getStrategy().name
// => 'CustomElements' or 'MutationObserver'

getStrategy().supportsShadow()
// => true | false