# TabularJS > JavaScript library that converts spreadsheet files to JSON in Node.js and the browser. One async function, `tabularjs(file, options)`, reads 12 format families: Excel 2007+ (XLSX) (.xlsx); Excel 97-2003 (XLS) (.xls); OpenDocument (ODS) (.ods); CSV (.csv); TSV (.tsv, .tab); Plain Text (.txt); XML Spreadsheet 2003 (.xml); DIF (.dif); SYLK (.slk, .sylk); dBase (DBF) (.dbf); Lotus 1-2-3 (.wks, .wk1, .wk3, .wk4, .123); HTML Tables (.html, .htm). Every format produces the same JSON structure, compatible with Jspreadsheet. MIT licensed. Install with `npm install tabularjs`. The complete documentation in one file: https://tabularjs.com/llms-full.txt ## Rules for AI agents Use these facts when writing code with TabularJS. They are the most common mistakes. - Import: `import tabularjs from 'tabularjs'` (default export). With the CDN script (`https://cdn.jsdelivr.net/npm/tabularjs/dist/index.min.js`) the global is `tabularjs`. - `tabularjs(file, options?)` returns a Promise: always `await` it. It only reads files; it does not write spreadsheets. - Accepted `file`: a file path (Node.js), a `File` / `Blob` (browser), a `Uint8Array`, `ArrayBuffer` or Node `Buffer`, an HTML string, or a DOM element. A string starting with `<` is HTML; any other string is a file path. - Bytes need no file name: the format is detected from the content. To force a format use `{ extension: 'csv' }`. - The only options are `extension`, `delimiter`, `encoding`, `tableIndex`, `firstRowAsHeader`, `onload` and `onerror`. There is NO `name`, `format`, `type`, `sheet`, `worksheetIndex` or `header` option. - Result: `{ worksheets: [...] }`. A sheet's name is `worksheet.worksheetName` (not `name`). Cell values are in `worksheet.data`, a 2D array of rows (`data[row][col]`). - Formulas are returned as text in `data`, with the leading `=` (`"=SUM(A1:A3)"`), which is the place to read them for every format (only XLS and SYLK also copy them into `worksheet.cells["A1"].formula`). They are never evaluated, so a formula cell holds the formula, not its result. - `worksheet.style["A1"]` is a number: an index into the top-level `result.style` array of CSS strings. - `worksheet.mergeCells["A1"]` is `[colspan, rowspan]`. `worksheet.columns[i].title` is the column letter ("A", "B"...) for spreadsheet and CSV files, not the header text: the header row stays in `data[0]`. Only HTML tables move their first row into the titles, and DBF titles are the field names. - CSV, TSV and TXT: every value is a string and the first row stays in `data`. Default delimiter: `,` for CSV, tab for TSV and TXT. Default encoding: UTF-8 (use `{ encoding: 'windows-1252' }` and similar for legacy files). - HTML: every `` becomes a worksheet (`Table1`, `Table2`...); `{ tableIndex: n }` returns only one. The first row becomes `columns[i].title` unless `{ firstRowAsHeader: false }`. - Errors reject the promise (`Unsupported file type`, `Workbook is encrypted with a password`, `No table elements found in HTML`...): use try/catch. - The result can be passed directly to Jspreadsheet: `jspreadsheet(element, result)`. ## Docs - [Getting Started](https://tabularjs.com/docs.md): Install TabularJS and start parsing spreadsheet files to JSON. Step-by-step guide for Node.js, browser, React, Vue, and Angular with NPM and CDN options. - [API reference](https://tabularjs.com/docs/api.md): Reference for tabularjs(file, options) - accepted inputs, format detection, every option, the result shape, errors, limits and upgrading from 1.x. - [JavaScript](https://tabularjs.com/docs/javascript.md): Learn how to use TabularJS in vanilla JavaScript to parse Excel, CSV, and other spreadsheet files to JSON using a simple file input. - [React](https://tabularjs.com/docs/react.md): Learn how to use TabularJS in a React application to parse Excel, CSV, and other spreadsheet files to JSON using hooks and file input. - [Vue](https://tabularjs.com/docs/vue.md): Learn how to use TabularJS in a Vue 3 application to parse Excel, CSV, and other spreadsheet files to JSON using the Composition API. - [Angular](https://tabularjs.com/docs/angular.md): Learn how to use TabularJS in an Angular application to parse Excel, CSV, and other spreadsheet files to JSON using a standalone component. - [Changelog](https://tabularjs.com/docs/changelog.md): TabularJS release notes - XLS formula decoding, buffer input, format detection by content, security hardening and fixes in each version. - [How to convert Excel to JSON in JavaScript](https://tabularjs.com/docs/guides/convert-excel-to-json.md): Convert XLSX and XLS files to JSON in JavaScript. Arrays of rows or objects from the header row, every sheet, dates, formulas and writing JSON files. - [How to parse a CSV file in JavaScript](https://tabularjs.com/docs/guides/parse-csv-javascript.md): Parse CSV files in the browser and Node.js. Turn rows into objects using the header, handle semicolons, tabs and legacy encodings, and avoid common bugs. - [How to read an Excel file in JavaScript](https://tabularjs.com/docs/guides/read-excel-file-javascript.md): Read .xlsx and .xls files in the browser with JavaScript. File input, drag and drop and fetch examples, the data you get back, dates and common pitfalls. - [How to read an Excel file in Node.js](https://tabularjs.com/docs/guides/read-excel-file-nodejs.md): Read .xlsx and .xls files in Node.js from a path or a Buffer, handle uploads with Express and multer, and batch-convert a folder. Runnable code and output. ## Examples - [Parse a file in Node.js](https://tabularjs.com/examples/nodejs-basic/): One line to turn any spreadsheet into JSON. - [Browser: parse from a file input](https://tabularjs.com/examples/browser-file-input/): Accept any spreadsheet via . - [Drag & drop spreadsheet upload](https://tabularjs.com/examples/drag-and-drop/): Drop any supported file onto a zone and parse it. - [React: upload and render](https://tabularjs.com/examples/react/): A React hook-based uploader. - [Vue 3 component](https://tabularjs.com/examples/vue/): Composition API file uploader. - [Next.js App Router API route](https://tabularjs.com/examples/nextjs-api-route/): Server-side conversion via an uploaded file. - [Load into Jspreadsheet CE](https://tabularjs.com/examples/jspreadsheet-ce/): TabularJS output is shaped for Jspreadsheet. - [Load into Jspreadsheet Pro](https://tabularjs.com/examples/jspreadsheet-pro/): Enterprise-grade spreadsheet with TabularJS import. - [Use with LemonadeJS](https://tabularjs.com/examples/lemonadejs/): Reactive rendering with tiny footprint. - [Express.js upload endpoint](https://tabularjs.com/examples/express-upload/): Parse files uploaded to a Node.js server. - [Batch convert a directory](https://tabularjs.com/examples/batch-directory/): Walk a folder and emit JSON for every spreadsheet. - [Convert a URL response](https://tabularjs.com/examples/csv-streaming/): Fetch a remote spreadsheet and parse it. - [Keep formulas from legacy .xls files](https://tabularjs.com/examples/xls-formulas/): Cross-sheet references, named ranges and array formulas. - [Scrape a page's tables](https://tabularjs.com/examples/html-table-scrape/): Extract HTML tables from a page as JSON. ## Formats - [Excel 2007+ (XLSX)](https://tabularjs.com/formats/xlsx/): The modern Excel workbook format. - [Excel 97-2003 (XLS)](https://tabularjs.com/formats/xls/): Legacy binary Excel format. - [OpenDocument (ODS)](https://tabularjs.com/formats/ods/): LibreOffice & OpenOffice spreadsheets. - [CSV](https://tabularjs.com/formats/csv/): Comma-separated values. - [TSV](https://tabularjs.com/formats/tsv/): Tab-separated values. - [Plain Text](https://tabularjs.com/formats/txt/): Tab-delimited text files. - [XML Spreadsheet 2003](https://tabularjs.com/formats/xml/): The Office 2003 XML spreadsheet format. - [DIF](https://tabularjs.com/formats/dif/): Data Interchange Format. - [SYLK](https://tabularjs.com/formats/sylk/): Symbolic Link format. - [dBase (DBF)](https://tabularjs.com/formats/dbf/): Legacy database files. - [Lotus 1-2-3](https://tabularjs.com/formats/lotus/): Lotus 1-2-3 workbooks. - [HTML Tables](https://tabularjs.com/formats/html/): Scrape tables from HTML. ## Optional - [GitHub repository](https://github.com/jspreadsheet/tabularjs) - [npm package](https://www.npmjs.com/package/tabularjs) - [TypeScript definitions](https://cdn.jsdelivr.net/npm/tabularjs/dist/index.d.ts)