# to-spreadsheet

> npm package to create spreadsheet in node environment and in browser

Latest version **1.4.1** (published 2026-09-13) · MIT license · 0 weekly downloads

## Install

```sh
npm install to-spreadsheet
pnpm add to-spreadsheet
yarn add to-spreadsheet
bun add to-spreadsheet
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 1.4.1 |
| Published | 2026-09-13 |
| First published | 2022-05-27 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=14.0.0 |
| Dependencies | 3 |
| Unpacked size | 98.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 5 |
| Author | Maifee Ul Asad |
| Maintainers | maifeeulasad |
| Keywords | excel, xlsx, spreadsheet, workbook, worksheet, cell, border, color, date, formula, equation, export, generate, browser, node, typescript, javascript, office, microsoft, csv, data-export, file-generation, styling, formatting, import, read, reader, parse, parser, xlsx-reader |

## Links

- npm: https://www.npmjs.com/package/to-spreadsheet
- Repository: https://github.com/maifeeulasad/to-spreadsheet
- Homepage: https://github.com/maifeeulasad/to-spreadsheet#readme
- Issues: https://github.com/maifeeulasad/to-spreadsheet/issues
- npm.io page: https://npm.io/package/to-spreadsheet

## Dependencies (3)

- [jszip](https://npm.io/package/jszip.md) ^3.10.1
- [archiver](https://npm.io/package/archiver.md) ^7.0.1
- [file-saver](https://npm.io/package/file-saver.md) ^2.0.5

## Alternatives

- [csv-to-markdown-table](https://npm.io/package/csv-to-markdown-table.md) — 47.0K weekly downloads
- [@sapphire/ratelimits](https://npm.io/package/@sapphire/ratelimits.md) — 4.4K weekly downloads
- [js-csvparser](https://npm.io/package/js-csvparser.md) — 2.0K weekly downloads
- [@adadapted/js-sdk](https://npm.io/package/@adadapted/js-sdk.md) — 251 weekly downloads
- [@grapecity/spread-sheets-sparklines](https://npm.io/package/@grapecity/spread-sheets-sparklines.md) — 103 weekly downloads

## Recent versions

- 1.4.1 (latest) — 2026-09-13
- 1.4.0 — 2026-09-13
- 1.3.0 — 2025-08-09
- 1.2.0 — 2025-08-09
- 1.1.5 — 2023-10-01
- 1.1.4 — 2023-10-01
- 1.1.3 — 2023-10-01
- 1.1.2 — 2023-09-30
- 1.1.1 — 2023-09-30
- 1.1.0 — 2023-09-29
- 1.0.0 — 2023-09-22
- 0.1.0 — 2022-11-14
- 0.0.3 — 2022-11-13
- 0.0.2 — 2022-10-17
- 0.0.1 — 2022-05-27

## README

# to-spreadsheet
npm package to create **and read** spreadsheets in node environment and in browser


[![npm version](https://img.shields.io/npm/v/to-spreadsheet.svg)](https://www.npmjs.com/package/to-spreadsheet)
[![minified](https://badgen.net/bundlephobia/min/to-spreadsheet)](https://badgen.net/bundlephobia/min/to-spreadsheet)
[![minified + gzipped](https://badgen.net/bundlephobia/minzip/to-spreadsheet)](https://badgen.net/bundlephobia/minzip/to-spreadsheet)

[![GitHub stars](https://img.shields.io/github/stars/maifeeulasad/to-spreadsheet)](https://github.com/maifeeulasad/to-spreadsheet/stargazers)
[![GitHub watchers](https://img.shields.io/github/watchers/maifeeulasad/to-spreadsheet)](https://github.com/maifeeulasad/to-spreadsheet/watchers)
[![Commits after release](https://img.shields.io/github/commits-since/maifeeulasad/to-spreadsheet/latest/main?include_prereleases)](https://img.shields.io/github/commits-since/maifeeulasad/to-spreadsheet/latest/main?include_prereleases)

# NPM
```
npm i to-spreadsheet
```


# Usage
[![Open in CodeSandbox](https://img.shields.io/badge/Open%20in-CodeSandbox-blue?logo=codesandbox)](https://codesandbox.io/s/to-spreadsheet-example-hdmrvc?file=/src/App.tsx)

```ts
import { generateExcel , EnvironmentType, skipCell, writeEquation } from 'to-spreadsheet/lib/index';

const sampleData = [
  {
    title: 'Maifee1', content: [
      ['meaw', 'grrr'],
      ['woof', 'smack'],
      [1],
      [1, 2],
      [1, 2, 3, writeEquation('SUM(A5,C5)')],
    ]
  },
  { title: 'Maifee2', content: [[1], [1, skipCell(3), 2]] },
  { title: 'Maifee3', content: [['meaw', undefined, "meaw"], ["woof", 'woof']] }
]

generateExcel(sampleData); // <-- by default generate XLSX for node
generateExcel(sampleData, EnvironmentType.BROWSER); // <-- for browser
```

# Reading / Importing

`to-spreadsheet` can also read spreadsheets back into plain JavaScript values. The
reader works in **both Node.js and the browser** and covers `.xlsx` (OOXML) files —
those produced by this library as well as ordinary files from Excel and other tools —
plus CSV text.

## Reading an `.xlsx` file

```ts
import { readExcel } from 'to-spreadsheet/lib/index';

// Node.js: pass a file path, a Buffer, or a Uint8Array/ArrayBuffer
const workbook = await readExcel('./report.xlsx');

// Browser: pass a File/Blob (e.g. from <input type="file">) or an ArrayBuffer
// const workbook = await readExcel(file);

workbook.sheets.forEach((sheet) => {
  console.log(sheet.title);   // sheet (tab) name
  console.log(sheet.rows);    // ReadCellValue[][] — a dense grid, gaps are null
});
```

Each cell comes back as a `string`, `number`, `boolean`, `Date` (for date-formatted
cells) or `null` (empty). Date conversion can be disabled to get the raw Excel serial:

```ts
const workbook = await readExcel('./report.xlsx', { cellDates: false });
```

Formula cells are surfaced on an optional parallel `sheet.formulas` grid (the formula
text without the leading `=`), present only when a sheet contains at least one formula.

## Parsing CSV

```ts
import { parseCsv } from 'to-spreadsheet/lib/index';

const rows = parseCsv('name,age\nalice,30\n"bob, jr.",25');
// [["name","age"], ["alice","30"], ["bob, jr.","25"]]

// custom delimiter
const tsv = parseCsv(tabText, { delimiter: '\t' });
```

`parseCsv` follows RFC 4180: quoted fields, escaped quotes (`""`), embedded commas and
newlines, `\r\n`/`\n` line endings, and a leading UTF-8 BOM are all handled.

# Cell Features

## Dates

You can create date cells that are properly formatted in Excel:

### Basic Date Usage

```ts
import { 
  generateExcel, 
  createDateCell, 
  createBorderedDateCell,
  createBackgroundDateCell 
} from 'to-spreadsheet/lib/index';

const data = [
  {
    title: 'DateDemo',
    content: [
      [
        'Event',
        'Date',
        'Styled Date'
      ],
      [
        'Project Start',
        createDateCell(new Date('2024-01-01')),
        createBorderedDateCell(new Date('2024-01-15'), createAllBorders())
      ],
      [
        'Milestone',
        createDateCell(new Date()),
        createBackgroundDateCell(new Date('2024-12-25'), '#FFCCCC')
      ]
    ]
  }
];
```

### Date Helper Functions

- `createDateCell(date, style?)` - Creates a date cell with optional styling
- `createBorderedDateCell(date, border)` - Creates a date cell with borders
- `createBackgroundDateCell(date, backgroundColor)` - Creates a date cell with background color

## Colors

You can add background and foreground colors to cells:

### Basic Color Usage

```ts
import { 
  generateExcel, 
  createBackgroundCell, 
  createForegroundCell, 
  createColoredCell,
  createStyledCell
} from 'to-spreadsheet/lib/index';

const data = [
  {
    title: 'ColorDemo',
    content: [
      [
        'Feature',
        'Background Color',
        'Foreground Color',
        'Both Colors'
      ],
      [
        'Yellow Background',
        createBackgroundCell('Highlighted', '#FFFF00'),
        createForegroundCell('Red Text', '#FF0000'),
        createColoredCell('Green BG, Red Text', '#00FF00', '#FF0000')
      ],
      [
        'Complex Styling',
        createStyledCell('Full Style', {
          backgroundColor: '#FFFFCC',
          foregroundColor: '#0000FF',
          border: createAllBorders(BorderStyle.thick, '#000000')
        }),
        'Regular cell',
        42
      ]
    ]
  }
];
```

### Color Helper Functions

- `createBackgroundCell(value, backgroundColor)` - Creates cell with background color
- `createForegroundCell(value, foregroundColor)` - Creates cell with text color
- `createColoredCell(value, backgroundColor, foregroundColor)` - Creates cell with both colors
- `createStyledCell(value, style)` - Creates cell with full styling options

# Features
 - [x] Multiple sheet support
 - [x] Equations
 - [x] Cell borders
 - [x] Cell styling (background colors, foreground colors, dates)
 - [x] Date cells with proper Excel formatting
 - [x] Cell alignment (horizontal and vertical)
 - [ ] Sheet styling

## Cell Borders

You can add borders to cells using the border functionality:

### Basic Border Usage

```ts
import { 
  generateExcel, 
  createBorderedCell, 
  createAllBorders, 
  createTopBorder, 
  createBottomBorder, 
  createLeftBorder, 
  createRightBorder,
  BorderStyle 
} from 'to-spreadsheet/lib/index';

const data = [
  {
    title: 'BorderDemo',
    content: [
      [
        // Create cells with all borders
        createBorderedCell('Header 1', createAllBorders(BorderStyle.thick, '#000000')),
        createBorderedCell('Header 2', createAllBorders(BorderStyle.thick, '#000000'))
      ],
      [
        // Create cells with specific borders
        createBorderedCell('Data 1', createTopBorder()),
        createBorderedCell(100, createRightBorder()),
        createBorderedCell('Final', createBottomBorder())
      ]
    ]
  }
];

generateExcel(data);
```

### Border Styles

Available border styles:
- `BorderStyle.none` - No border
- `BorderStyle.thin` - Thin border (default)
- `BorderStyle.medium` - Medium border
- `BorderStyle.thick` - Thick border  
- `BorderStyle.double` - Double border
- `BorderStyle.dotted` - Dotted border
- `BorderStyle.dashed` - Dashed border

### Border Helper Functions

**Border Creation:**
- `createAllBorders(style?, color?)` - Creates borders on all sides
- `createTopBorder(style?, color?)` - Creates only top border
- `createBottomBorder(style?, color?)` - Creates only bottom border
- `createLeftBorder(style?, color?)` - Creates only left border
- `createRightBorder(style?, color?)` - Creates only right border
- `createBorder(borderConfig)` - Creates custom border configuration

**Cell Creation:**
- `createBorderedCell(value, border)` - Creates a cell with border
- `createStyledCell(value, style)` - Creates a cell with custom styling

### Advanced Border Usage

```ts
import { createStyledCell, BorderStyle } from 'to-spreadsheet/lib/index';

// Custom border configuration
const customCell = createStyledCell('Custom', {
  border: {
    left: BorderStyle.double,
    top: BorderStyle.thin,
    right: BorderStyle.dashed,
    bottom: BorderStyle.thick,
    color: '#FF0000' // Red borders
  }
});

// Mix styled and regular cells
const data = [
  {
    title: 'Mixed',
    content: [
      [customCell, 'Regular Cell', 42]
    ]
  }
];
```

## Combined Styling

All styling features can be combined together:

```ts
import { 
  createStyledCell, 
  createAllBorders, 
  BorderStyle 
} from 'to-spreadsheet/lib/index';

const data = [
  {
    title: 'CombinedDemo',
    content: [
      [
        // Cell with background color, text color, and borders
        createStyledCell('Fully Styled', {
          backgroundColor: '#FFFFCC',    // Light yellow background
          foregroundColor: '#0000FF',    // Blue text
          border: createAllBorders(BorderStyle.thick, '#FF0000') // Red thick border
        }),
        
        // Date with background and border
        createDateCell(new Date(), {
          backgroundColor: '#CCFFCC',    // Light green background
          border: createAllBorders(BorderStyle.double, '#008000') // Green double border
        }),
        
        // Regular cells for comparison
        'Plain text',
        42
      ]
    ]
  }
];
```

### Color Format

Colors should be specified in hex format:
- `#FF0000` - Red
- `#00FF00` - Green  
- `#0000FF` - Blue
- `#FFFF00` - Yellow
- `#FF00FF` - Magenta
- `#00FFFF` - Cyan
- `#000000` - Black
- `#FFFFFF` - White
- `#CCCCCC` - Light gray

## Cell Alignment

You can align cell content both horizontally and vertically:

### Basic Alignment Usage

```ts
import { 
  generateExcel, 
  createHorizontallyAlignedCell, 
  createVerticallyAlignedCell, 
  createAlignedCell,
  createCenteredCell,
  HorizontalAlignment, 
  VerticalAlignment 
} from 'to-spreadsheet/lib/index';

const data = [
  {
    title: 'AlignmentDemo',
    content: [
      [
        'Feature',
        'Horizontal',
        'Vertical',
        'Both'
      ],
      [
        'Left Align',
        createHorizontallyAlignedCell('Left Text', HorizontalAlignment.left),
        createVerticallyAlignedCell('Top Text', VerticalAlignment.top),
        createAlignedCell('Top-Left', HorizontalAlignment.left, VerticalAlignment.top)
      ],
      [
        'Center Align',
        createHorizontallyAlignedCell('Center Text', HorizontalAlignment.center),
        createVerticallyAlignedCell('Center Text', VerticalAlignment.center),
        createCenteredCell('Full Center')
      ],
      [
        'Right Align',
        createHorizontallyAlignedCell('Right Text', HorizontalAlignment.right),
        createVerticallyAlignedCell('Bottom Text', VerticalAlignment.bottom),
        createAlignedCell('Bottom-Right', HorizontalAlignment.right, VerticalAlignment.bottom)
      ]
    ]
  }
];
```

### Horizontal Alignment Options

- `HorizontalAlignment.general` - General alignment (Excel default)
- `HorizontalAlignment.left` - Left alignment
- `HorizontalAlignment.center` - Center alignment  
- `HorizontalAlignment.right` - Right alignment
- `HorizontalAlignment.fill` - Fill alignment
- `HorizontalAlignment.justify` - Justify alignment
- `HorizontalAlignment.centerContinuous` - Center across selection
- `HorizontalAlignment.distributed` - Distributed alignment

### Vertical Alignment Options

- `VerticalAlignment.top` - Top alignment
- `VerticalAlignment.center` - Center alignment
- `VerticalAlignment.bottom` - Bottom alignment
- `VerticalAlignment.justify` - Justify alignment
- `VerticalAlignment.distributed` - Distributed alignment

### Alignment Helper Functions

- `createHorizontallyAlignedCell(value, alignment)` - Creates cell with horizontal alignment
- `createVerticallyAlignedCell(value, alignment)` - Creates cell with vertical alignment
- `createAlignedCell(value, horizontal, vertical)` - Creates cell with both alignments
- `createCenteredCell(value)` - Creates center-aligned cell (convenience function)

### Combined with Other Features

Alignment works seamlessly with all other styling features:

```ts
import { 
  createStyledCell, 
  HorizontalAlignment, 
  VerticalAlignment,
  createAllBorders, 
  BorderStyle 
} from 'to-spreadsheet/lib/index';

const data = [
  {
    title: 'ComplexStyling',
    content: [
      [
        // Full styling with alignment, colors, and borders
        createStyledCell('Complete Style', {
          horizontalAlignment: HorizontalAlignment.center,
          verticalAlignment: VerticalAlignment.center,
          backgroundColor: '#CCFFCC',
          foregroundColor: '#FF0000',
          border: createAllBorders(BorderStyle.thick, '#000000')
        }),
        
        // Aligned date cell
        createDateCell(new Date(), {
          horizontalAlignment: HorizontalAlignment.right,
          verticalAlignment: VerticalAlignment.center,
          backgroundColor: '#FFFFCC'
        }),
        
        // Simple centered text
        createCenteredCell('Centered')
      ]
    ]
  }
];
```

---
_Source: https://npm.io/package/to-spreadsheet · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._