XML-to-React

Converts an XML document into a React tree.

Typescript port of unmaintained Conde Nast implementation.

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
• tagStack {string[]} - (optional - only passed if tagStackEnabled option is true). Current (xml document) tag name is at the top of the stack. Followed by parent, etc.

Example

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

Special Converter Names

If the Converter is named $TextNode, then this supplied converter will be applied to all Text Nodes. This converter will be passed arguments value and data. (instead of the standard attributes and data). value is the text node's text content.

  // Example of mapping all text nodes to a span with value='text node content' attribute.

  const xmlToReact = new XMLToReact({
    $TextNode: (value) => ({type: 'span', props: {value}})
  }, {includeRawXmlAsProp: false});

  const r = xmlToReact.convert('<div>hello</div>');

  // r contains <span value="hello" />

XMLToReact constructor

The XMLToReact class is instantiated with a map of converters.

{
  nodeName: converterFunction
}

for example:

new XmlToReact(
{ 
  FirstName : (attrs) => ({ type : 'div', props: attrs}),
  LastName : (attrs) => ({ type : 'div', props: attrs}),
});

Options can XmlToReact also be passed to the XmlToReact constructor.

for example:

new XmlToReact(
{ 
  FirstName : (attrs) => ({ type : 'div', props: attrs}),  
}, {includeRawXmlAsProp : true});

|option | description | type | default | |------ | ----------- | ---- | ------- | | includeRawXmlAsProp | include outer xml as property named raw | boolean | false | | tagStackEnabled | pass tag stack array as third argument to converter function | boolean |false |

convert( xml, data, tagStack )

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