xml2js Documentation

You can install xml2js and its dependencies using npm or Bower.

npm install xml2js

bower install xml2js

You can use parseStringPromise to handle XML parsing with Promises. This can be called either on a Parser instance or directly from the xml2js module.

var xml2js = require('xml2js');
var xml = '<foo></foo>';

// With parser
var parser = new xml2js.Parser(/* options */);
parser.parseStringPromise(xml).then(function (result) {
  console.dir(result);
  console.log('Done');
})
.catch(function (err) {
  // Failed
});

// Without parser
xml2js.parseStringPromise(xml /*, options */).then(function (result) {
  console.dir(result);
  console.log('Done');
})
.catch(function (err) {
  // Failed
});

Use the xml2js.Builder class to convert JavaScript objects into XML strings via the buildObject(obj) method.

To specify attributes, use the $ key within the object. To specify text content, use the _ key.

To declare XML namespaces (xmlns), include them as attributes in the $ object.

For more structured usage, instantiate a new xml2js.Parser. This is the recommended approach when parsing multiple files. You can call .parseString(data, callback) on the parser instance.

Starting from version 0.2.8, you can omit the new keyword when creating a Parser and the library will handle it for you.

var fs = require('fs'),
    xml2js = require('xml2js');

var parser = new xml2js.Parser();
fs.readFile(__dirname + '/foo.xml', function(err, data) {
    parser.parseString(data, function (err, result) {
        console.dir(result);
        console.log('Done');
    });
});

You can transform XML elements during parsing by providing arrays of processor functions to the following options:

• tagNameProcessors: Transforms tag names.
• attrNameProcessors: Transforms attribute names.
• valueProcessors: Transforms element values (receives value and name).
• attrValueProcessors: Transforms attribute values (receives value and name).

Each processor function should follow the signature: function (input) { return transformedInput; } (or function (value, name) for value processors).

function nameToUpperCase(name){
    return name.toUpperCase();
}

parseString(xml, {
  tagNameProcessors: [nameToUpperCase],
  attrNameProcessors: [nameToUpperCase],
  valueProcessors: [nameToUpperCase],
  attrValueProcessors: [nameToUpperCase]
  }, function (err, result) {
    // processed data
});

For a quick, one-off parsing task, use the parseString method directly from the required module. This method accepts the XML string, an optional options object, and a callback function function (err, result).

Note: This works starting from version 0.2.3.

var parseString = require('xml2js').parseString;
var xml = "<root>Hello xml2js!</root>";
parseString(xml, function (err, result) {
    console.dir(result);
});

Commonly used processor functions available for tagNameProcessors, attrNameProcessors, valueProcessors, and attrValueProcessors:

• normalize: Transforms the name to lowercase (automatically used if options.normalize is true).
• firstCharLowerCase: Transforms the first character to lower case (e.g., 'MyTagName' -> 'myTagName').
• stripPrefix: Strips the XML namespace prefix (e.g., <foo:Bar/> -> 'Bar'). Note: xmlns prefix is NOT stripped.
• parseNumbers: Parses integer-like strings as integers and float-like strings as floats.
• parseBooleans: Parses boolean-like strings to booleans (e.g., 'true' -> true).