@onparallel/write-excel-file-hide-rows-and-columns

Hide rows and columns custom feature for write-excel-file.

Adds support for marking individual rows and columns as hidden in the generated .xlsx, without requiring a fork of the base package. Hidden rows/columns are preserved in the file (Excel users can right-click → "Unhide" to reveal them); they are not deleted.

Install

npm install write-excel-file @onparallel/write-excel-file-hide-rows-and-columns

write-excel-file is a peer dependency (^4.0.0). The package is published publicly under the @onparallel scope — no authentication required to install.

Usage

Register the feature when calling writeXlsxFile(). write-excel-file/node's built-in SheetOptions does not know about hiddenRows / hiddenColumns, so intersect it with the HideRowsAndColumnsSheetOptions type exported by this package:

import writeXlsxFile, { type SheetOptions } from 'write-excel-file/node'
import hideRowsAndColumns, {
	type HideRowsAndColumnsSheetOptions
} from '@onparallel/write-excel-file-hide-rows-and-columns'

const sheetOptions: SheetOptions<any> & HideRowsAndColumnsSheetOptions = {
	sheet: 'Sheet1',
	hiddenRows: [4, 6, { from: 11, to: 21 }], // hides rows 4, 6, and 11–21 (1-based)
	hiddenColumns: [2, { from: 5, to: 7 }] // hides columns B and E–G (1-based)
}

await writeXlsxFile(data, sheetOptions, { features: [hideRowsAndColumns] }).toFile('out.xlsx')

If you use the intersection in many places, alias it locally: type MySheetOptions = SheetOptions<any> & HideRowsAndColumnsSheetOptions.

Why not module augmentation? write-excel-file/node re-exports its types with export type { ... }, which TypeScript does not allow downstream packages to augment.

API

Both hiddenRows and hiddenColumns accept the same shape: an array of HiddenRange, where each entry is either a single 1-based index or a { from, to } range (inclusive, also 1-based).

| Type | Example | Meaning | | ------------------------------ | ---------------------- | --------------------------------------------------- | | number | 5 | Hide a single row/column at index 5 (row 5 / col E) | | { from: number, to: number } | { from: 10, to: 20 } | Hide rows/columns 10 through 20 (inclusive) |

export type HiddenRange = number | { from: number; to: number }

export interface HideRowsAndColumnsSheetOptions {
	hiddenRows?: HiddenRange[]
	hiddenColumns?: HiddenRange[]
}

Indexing: 1-based, matching write-excel-file's own row/column numbering convention (row 1 = first row, column 1 = column A) and the visible row numbers in Excel.

Limits: Excel's hard maxima — 1,048,576 rows and 16,384 columns — are enforced. Indices below 1, non-integers, and from > to throw.

Combining with custom column widths

If you also pass columns with width to writeXlsxFile(), this feature will merge <col hidden="1"/> entries into the existing <cols> block rather than replacing it. Widths set by the user are preserved.

const sheetOptions: SheetOptions<any> & HideRowsAndColumnsSheetOptions = {
	sheet: 'Sheet1',
	columns: [{ width: 20 }, {}, { width: 30 }],
	hiddenColumns: [2] // hides column B; A and C keep their custom widths
}

How it works

The feature hooks into xl/worksheets/sheet{id}.xml and:

• For hidden columns: builds a <cols> block with <col min="X" max="Y" hidden="1"/> entries (1-based indices, consecutive indices are coalesced into ranges) and inserts it in the canonical position between <sheetFormatPr> and <sheetData> — or appends to an existing <cols> if the user also passed custom widths.
• For hidden rows: adds the hidden="1" attribute to existing <row r="N"> elements that write-excel-file already emits. Rows with no data have no <row> element in the XML and are silently skipped (Excel still treats them as hidden when "unhide" is applied).

See src/hideRowsAndColumns.ts for the implementation.

Examples

The examples/ folder contains runnable TypeScript scripts that emit .xlsx files next to themselves. Open the generated files in Excel/Numbers/LibreOffice to confirm rows and columns are hidden as expected.

npm install
npx tsx examples/hide-rows.ts        # run a single example
npm run examples                      # run them all

See examples/README.md for the full list.

Development

npm install
npm test          # vitest
npm run typecheck # tsc --noEmit
npm run build     # emit dist/ via tsc

License

MIT