Olical/react-faux-dom


DOM like structure that renders to React

http://oli.me.uk/2015/09/09/d3-within-react-the-right-way/

License: Unlicense

Language: JavaScript

Keywords: d3, dom, javascript, react


react-faux-dom npm version CDNJS Build Status js-standard-style Join the chat at https://gitter.im/Olical/react-faux-dom

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

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.

Example

Default

This style of calling createElement and toReact is the default API, it's easy to use and fits into the normal React flow but won't allow you to perform animations or D3 force layouts, for example.

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>

With animation helper

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)

Limitations

This library is intended to be used to build a React DOM tree from some mutable intermediate value which is then thrown away inside a render function. This means things that require mutation of the DOM, such as D3's animations, zooming, dragging and brushing will not work.

Static charts will work fine out of the box, you can use this tool to translate SVG tools into DOM managed by React easily. If you wish to start adding in animations you'll have to use the withFauxDOM higher order component mentioned above and in a few of the examples.

Before you go to use this tool, stop and think:

  • Am I trying to build static DOM within a render method? - This is fine.
  • Am I trying to hook up timers and event listeners with a 3rd party tool to manipulate some DOM after I have inserted it into the page? - This is not going to work.

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

Independent documents

By default all Elements share an emulated window at el.ownerDocument.defaultView you can create independent 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 = getParagraph();

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

More usage info:

Related articles:

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!

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.

Project Statistics

Sourcerank 15
Repository Size 723 KB
Stars 1,197
Forks 92
Watchers 25
Open issues 3
Dependencies 650
Contributors 17
Tags 36
Created
Last updated
Last pushed

Top Contributors See all

Oliver Caldwell Thibaut Tiberghien David Waller Thomas Grainger Phil Plückthun Seb Insua Evan Hensleigh Alex Yuly The Gitter Badger Brett Statman Sergi Mansilla Howard Chi GeorgeStrakhov Nick Balestra Pedram Emrouznejad npm-to-cdn-bot (by Forbes Lindesay) Ed Mazurek

Packages Referencing this Repo

react-faux-dom
DOM like data structure to be mutated by D3 et al, then rendered to React elements
Latest release 4.4.1 - Updated - 1.2K stars
react-faux-dom-roadcert-edition
DOM like data structure to be mutated by D3 et al, then rendered to React elements
Latest release 0.0.1 - Published - 1.2K stars

Recent Tags See all

v4.4.1 March 29, 2019
v4.4.0 February 14, 2019
v4.3.0 February 12, 2019
v4.2.0 June 17, 2018
v4.1.0 November 08, 2017
v4.0.5 October 10, 2017
v4.0.4 October 10, 2017
v4.0.3 June 03, 2017
v4.0.2 June 01, 2017
v4.0.1 June 01, 2017
v4.0.0 May 28, 2017
v3.1.0 April 19, 2017
v3.0.1 March 04, 2017
v3.0.0 September 01, 2016
v2.7.1 July 20, 2016

Interesting Forks See all

tibotiber/react-faux-dom
DOM like structure that renders to React
JavaScript - Unlicense - Last pushed - 1 stars - 1 forks

Something wrong with this page? Make a suggestion

Last synced: 2019-03-30 01:38:21 UTC

Login to resync this repository