Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »


    Table to JSON

    Attempts to convert HTML tables into JSON.

    Can be passed the markup for a single table as a string, a fragment of HTML or an entire page or just a URL (with an optional callback function; promises also supported).

    The response is always an array. Every array entry in the response represents a table found on the page (in same the order they were found in the HTML).


    Tables with headings in the first column

    If a table contains headings in the first column you might get an unexpected result, but you can pass a second argument with options with { useFirstRowForHeadings: true } to have it treat the first column as it would any other cell.

      { useFirstRowForHeadings: true },
      function(tablesAsJson) {

    Tables with HTML

    The following options are true by default, which converts all values to plain text to give you an easier more readable object to work with:

    • stripHtmlFromHeadings
    • stripHtmlFromCells

    If your table contains HTML you want to parse (for example for links) you can set stripHtmlFromCells to false to treat it as raw text.

      { stripHtmlFromCells: false },
      function(tablesAsJson) {
        //Print out the 1st row from the 2nd table on the above webpage as JSON 

    Note: This doesn't work with nested tables, which it will still try to parse.

    You probably don't need to set stripHtmlFromHeadings to false (and setting it to false can make the results hard to parse), but if you do you can also set both at the same time by setting stripHtml to false.

    Duplicate column headings

    If there are duplicate column headings, subsequent headings are suffixed with a count:

    // Table
    |   abc |     1 |   def |     2 |
    // Example output
      PLACE: 'abc', VALUE: '1',
      PLACE_2: 'def', VALUE_2: '2',

    Options forceIndexAsNumber

    Instead of using column text (that sometime re-order the data), force an index as a number (string number).

    // Some JSON (Other rows)
      "0": "",
      "1": "A会",
      "2": "B会",
      "3": "C会",
      "4": "Something",
      "5": "Else",
      "6": ""
    // Some JSON (Other rows)

    Options, known issues and limitations

    This module only supports parsing basic tables with a simple horizontal set of headings and corresponding cells.

    It can give useless or weird results on tables that have complex structures (such as nested tables) or multiple headers (such as on both X and Y axis).

    You'll need to handle things like work out which tables to parse and (in most cases) clean up the data. You might want to combine it it with modules like json2csv or CsvToMarkdownTable.

    You might want to use it with a module like 'cheerio' if you want to parse specific tables identified by id or class (i.e. select them with cheerio and pass the HTML of them as a string).

    Example usage

    // Convert an HTML blob into an array of all the tables on the page
    var tabletojson = require('tabletojson');
    var tablesAsJson = tabletojson.convert(html);
    var firstTableAsJson = tablesAsJson[0];
    var secondTableAsJson = tablesAsJson[1];
    // Fetch a URL and parse all it's tables into JSON, using a callback
    var tabletojson = require('tabletojson');
    var url = '';
    tabletojson.convertUrl(url, function(tablesAsJson) {
      var listofSovereignStates = tablesAsJson[0];
    // Fetch a URL and parse all it's tables into JSON, using promises
    var tabletojson = require('tabletojson');
    var url = '';
    .then(function(tablesAsJson) {
      var standardAndPoorRatings = tablesAsJson[1];
      var fitchRatings = tablesAsJson[2];
    // Fetch a table from Wikipedia and combine with json2csv to convert to CSV
    var tabletojson = require('tabletojson');
    var json2csv = require('json2csv');
    var url = '';
    .then(function(tablesAsJson) {
      var standardAndPoorCreditRatings = tablesAsJson[1];
      json2csv({ data: standardAndPoorCreditRatings,
                 fields: [ 'Country', 'Outlook']
               }, function(err, csv) {
                /* Example output
                  "Abu Dhabi, UAE","Stable"


    Improvements, fixes and suggestions for better written modules that other people have created are welcome, as are bug reports against specific tables it is unable to handle.

    There are no tests for this library because I am a terrible person.

    If you'd like to fix that, that would be amazing.

    There are some example files included with this project that show usage and would be a good start for some tests if anyone would like to help out with that.

    If you submit a pull request, please add an example for your use case, so I can understand what you want it to do (as I want to get around to writing tests for this and want to understand the sort of use cases people have).


    Thank you to @roryok, Max Thyen (@maxthyen), Thor Jacobsen (@twjacobsen) and Michael Keller (@mhkeller) for improvements and bug fixes.


    npm i tabletojson

    Downloadsweekly downloads







    last publish


    • avatar