@condenast/xml-to-react

XML-to-React

Converts an XML document into a React tree.

Proudly built by:

Prerequisites

This library may only be used in projects using React version 0.13.x or greater.

Installation

npm install --save xml-to-react

This assumes you are using npm as your package manager.

Usage

import XMLToReact from 'xml-to-react';

const xmlToReact = new XMLToReact({/* converters */});
const reactTree = xmlToReact.convert(/* XML string */);

Simple Example

Convert XML nodes into DOM elements with any provided attributes

import ReactDOM from 'react-dom';
import XMLToReact from 'xml-to-react';
import MyListItem from './MyListItem';

const xmlToReact = new XMLToReact({
  Example: (attrs) => ({ type: 'ul', props: attrs }),
  Item: (attrs) => ({ type: MyListItem, props: attrs })
});

const reactTree = xmlToReact.convert(`
  <Example name="simple">
    <Item i="1">one</Item>
    <Item>two</Item>
    <Item>three</Item>
  </Example>
`);

ReactDOM.render('app-container', reactTree);

export default function MyListItem({ children, i }) {
  return <li data-i={i}>{children}</li>;
}

This example would render the following:

<div id="app-container">
  <ul name="simple">
    <li data-i="1">one</li>
    <li>two</li>
    <li>three</li>
  </ul>
</div>

Converters

Converters are required mapping functions that define how an XML node should be converted to React. A converter must return an object in the format { type, [props] }, which is intended to be passed to React.createElement.

• type - required tagName, React component, or React fragment
• props - (optional) props object

Example

function myConverter(attributes) {
  return {
    type: 'div',
    props: {
      className: 'test'
    }
  }
}

XMLToReact constructor

The XMLToReact class is instantiated with a map of converters.

{
  nodeName: converterFunction
}

convert( xml, data )

• xml {string} - xml node or document
• data {Object} - (optional) any data to be passed to all converters

Prior Art

• jsonmltoreact demonstrated this technique using JsonML, and serves as motivation for this project.

Thanks

• xmldom for providing a solid XML parser.
• Rollup for simple and quick module bundling.
• React for the innovation.

Contributors

See the list of contributors who participated in writing this library.

Changelog

1.0.0 - 2018-03-01

• Initial Release
• Changed XML parsing to use an internal interface.
• chore: Add travis-ci config and badge

<!-- Update the Unreleased comparison range with each release -->