react-faux-dom

react-faux-dom

DOM like data structure to be mutated by D3 et al, then rendered to React elements.

class SomeChart extends React.Component {
  render () {
    // Create your element.
    var el = ReactFauxDOM.createElement('div')

    // Change stuff using actual DOM functions.
    // Even perform CSS selections!
    el.style.setProperty('color', 'red')
    el.setAttribute('class', 'box')

    // Render it to React elements.
    return el.toReact()
  }
}

// Yields: <div style='color: red;' class='box'></div>

There is also an higher-order component available for convenience, giving you a clean API and animation support:

// Inside componentWillMount.
var faux = this.props.connectFauxDOM('div', 'chart')
d3.performSomeAnimation(faux)
this.props.animateFauxDOM(3500) // duration + margin

// Inside render.
return <div>{this.props.chart}</div>;

ReactFauxDOM supports a wide range of DOM operations and will fool most libraries but it isn't exhaustive (the full DOM API is ludicrously large). It supports enough to work with D3 but will require you to fork and add to the project if you encounter something that's missing.

You can think of this as a bare bones jsdom that's built to bridge the gap between the declarative React and the imperative JavaScript world. We just need to expand it as we go along since jsdom is a huge project that solves different problems.

I'm trying to keep it light so as not to slow down your render function. I want efficient, declarative and stateless code, but I don't want to throw away previous tools to get there.

Installation

You can install the package react-faux-dom from npm as you usually would. Then use webpack or browserify (etc) to bundle the source into your build. If you need a pre-built UMD version you can use unpkg.

You can find the latest version of the UMD version at https://unpkg.com/react-faux-dom/dist/ReactFauxDOM.min.js

Example

Complex usage with D3, ES6 modules and animations. Clone it from here, or try on in codesandbox.

import React from 'react'
import * as d3 from 'd3'
import {withFauxDOM} from 'react-faux-dom'

class MyReactComponent extends React.Component {
  componentDidMount () {
    const faux = this.props.connectFauxDOM('div', 'chart')
    d3.select(faux)
      .append('div')
      .html('Hello World!')
    this.props.animateFauxDOM(800)
  }

  render () {
    return (
      <div>
        <h2>Here is some fancy data:</h2>
        <div className='renderedD3'>
          {this.props.chart}
        </div>
      </div>
    )
  }
}

MyReactComponent.defaultProps = {
  chart: 'loading'
}

export default withFauxDOM(MyReactComponent)

Independant documents

By default all Elements share an emulated window at el.ownerDocument.defaultView you can create independant documents with:

import React from 'react'
import rfdFactory from 'react-faux-dom/lib/factory'

function getParagraph() {
  const { ReactFauxDOM } = rfdFactory();
  return new ReactFauxDOM.Element('p', someDiv);
}

const p1 = getParagraph();
const p2 = getPragraph();

assert(p1.ownerDocument !== p2.ownerDocument);

More usage info:

• Full documentation with current DOM API coverage
• An example static chart (source, article)
• An "hello world" example using the HOC (source, sandbox)
• An example animated chart using the HOC (source, sandbox)
• An example chart with D3 updates using the HOC (source, sandbox)
• A simple example using state and events (source, article)
• A d3 sankey diagram builder (source, demo)
• d3-react-sparkline, a small component I built at Qubit (source)
• component-kit, "UI-Kit for Rapidly Creating Dashboards" (source)
• A demo dashboard with multiple charts (source, demo)

Related articles:

• D3 within React the right way
• React + D3.js: Balancing Performance & Developer Experience
• A starting point on using D3 with React

Development

# Fetch the dependencies
make bootstrap

# Test
make test

# Test continually
make test-watch

Maintainers

This project is actively maintained by the following developers. Feel free to reach out if you'd like to join us and help out!

• @Olical
• @tibotiber

Unlicenced

Find the full unlicense in the UNLICENSE file, but here's a snippet.

This is free and unencumbered software released into the public domain.

Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means.

Do what you want. Learn as much as you can. Unlicense more software.

Changelog

v4.1.0

• Merge #123 - Expose drawFauxDOM in HOC.
• Merge #116 - Support independent documents with a factory.