Skip to main content

Sheet

The Sheet class represents a worksheet within a workbook. Sheets contain cells organized in rows and columns.

Properties​

name​

Get or set the sheet name.

get name(): string
set name(value: string)
console.log(sheet.name);
sheet.name = 'Sales Data';

dimensions​

Get the used range of the sheet.

get dimensions(): RangeDefinition | null

Returns null if the sheet is empty.

const dims = sheet.dimensions;
if (dims) {
  console.log(`Data from row ${dims.startRow} to ${dims.endRow}`);
  console.log(`Data from col ${dims.startCol} to ${dims.endCol}`);
}

rowCount / columnCount / cellCount​

Get counts of data in the sheet.

get rowCount(): number
get columnCount(): number
get cellCount(): number
console.log('Rows:', sheet.rowCount);
console.log('Columns:', sheet.columnCount);
console.log('Total cells:', sheet.cellCount);

Cell Access​

cell()​

Get or create a cell. Creates the cell if it doesn't exist.

// By A1 notation
cell(address: string): Cell

// By row and column (0-based)
cell(row: number, col: number): Cell
// A1 notation
sheet.cell('A1').value = 'Hello';
sheet.cell('B2').value = 42;

// Row/column indices
sheet.cell(0, 0).value = 'Hello'; // A1
sheet.cell(1, 1).value = 42;      // B2

getCell()​

Get a cell if it exists, without creating it.

getCell(address: string): Cell | undefined
getCell(row: number, col: number): Cell | undefined
const cell = sheet.getCell('A1');
if (cell) {
  console.log(cell.value);
}

hasCell()​

Check if a cell exists.

hasCell(address: string): boolean
hasCell(row: number, col: number): boolean
if (sheet.hasCell('A1')) {
  console.log('Cell A1 exists');
}

deleteCell()​

Delete a cell.

deleteCell(address: string): boolean
deleteCell(row: number, col: number): boolean
sheet.deleteCell('A1');

cells()​

Iterate over all cells.

*cells(): Generator<Cell>
for (const cell of sheet.cells()) {
  console.log(`${cell.address}: ${cell.value}`);
}

cellsInRange()​

Iterate over cells in a range.

*cellsInRange(range: string | RangeDefinition): Generator<Cell>
for (const cell of sheet.cellsInRange('A1:D10')) {
  console.log(cell.value);
}

Bulk Operations​

setValues()​

Set values from a 2D array.

setValues(startAddress: string, values: CellValue[][]): this
setValues(startRow: number, startCol: number, values: CellValue[][]): this
sheet.setValues('A1', [
  ['Name', 'Age', 'City'],
  ['Alice', 30, 'NYC'],
  ['Bob', 25, 'LA'],
]);

// Or with indices
sheet.setValues(0, 0, [
  ['Name', 'Age', 'City'],
  ['Alice', 30, 'NYC'],
]);

getValues()​

Get values as a 2D array.

getValues(range: string | RangeDefinition): CellValue[][]
const values = sheet.getValues('A1:C3');
console.log(values);
// [['Name', 'Age', 'City'], ['Alice', 30, 'NYC'], ['Bob', 25, 'LA']]

applyStyle()​

Apply a style to a range of cells.

applyStyle(range: string | RangeDefinition, style: CellStyle): this
sheet.applyStyle('A1:D1', {
  font: { bold: true },
  fill: { type: 'pattern', pattern: 'solid', foregroundColor: '#F3F4F6' },
});

clearRange()​

Clear all cells in a range.

clearRange(range: string | RangeDefinition): this
sheet.clearRange('A1:D10');

Merge Operations​

mergeCells()​

Merge cells in a range.

mergeCells(range: string | RangeDefinition): this

Throws: Error if the range overlaps with an existing merge.

sheet.cell('A1').value = 'Title';
sheet.mergeCells('A1:D1');

// Or with range definition
sheet.mergeCells({
  startRow: 0,
  startCol: 0,
  endRow: 0,
  endCol: 3,
});

unmergeCells()​

Unmerge a merged range.

unmergeCells(range: string | RangeDefinition): this

Throws: Error if no merge exists at the specified range.

sheet.unmergeCells('A1:D1');

merges​

Get all merge ranges.

get merges(): readonly MergeRange[]
sheet.merges.forEach(merge => {
  console.log(`Merge: ${merge.startRow},${merge.startCol} to ${merge.endRow},${merge.endCol}`);
});

Row Configuration​

getRow()​

Get row configuration.

getRow(index: number): RowConfig
interface RowConfig {
  height?: number;
  hidden?: boolean;
  outlineLevel?: number;
  style?: CellStyle;
}

setRow()​

Set row configuration.

setRow(index: number, config: RowConfig): this
sheet.setRow(0, {
  height: 30,
  style: { font: { bold: true } },
});

setRowHeight()​

Set row height.

setRowHeight(index: number, height: number): this
sheet.setRowHeight(0, 25); // 25 points

hideRow() / showRow()​

Hide or show a row.

hideRow(index: number): this
showRow(index: number): this
sheet.hideRow(5);
sheet.showRow(5);

rows​

Get all row configurations.

get rows(): ReadonlyMap<number, RowConfig>

Column Configuration​

getColumn()​

Get column configuration.

getColumn(index: number): ColumnConfig
interface ColumnConfig {
  width?: number;
  hidden?: boolean;
  outlineLevel?: number;
  style?: CellStyle;
}

setColumn()​

Set column configuration.

setColumn(index: number, config: ColumnConfig): this
sheet.setColumn(0, {
  width: 20,
  style: { alignment: { horizontal: 'left' } },
});

setColumnWidth()​

Set column width.

setColumnWidth(index: number, width: number): this
sheet.setColumnWidth(0, 15); // 15 characters

hideColumn() / showColumn()​

Hide or show a column.

hideColumn(index: number): this
showColumn(index: number): this
sheet.hideColumn(2);
sheet.showColumn(2);

columns​

Get all column configurations.

get columns(): ReadonlyMap<number, ColumnConfig>

View Configuration​

view​

Get sheet view settings.

get view(): SheetView
interface SheetView {
  showGridLines?: boolean;
  showRowColHeaders?: boolean;
  showZeros?: boolean;
  tabSelected?: boolean;
  zoomScale?: number;
  frozenRows?: number;
  frozenCols?: number;
  splitRow?: number;
  splitCol?: number;
}

setView()​

Set sheet view settings.

setView(view: Partial<SheetView>): this
sheet.setView({
  showGridLines: true,
  zoomScale: 100,
});

freeze()​

Freeze rows and columns.

freeze(rows: number, cols?: number): this
sheet.freeze(1);     // Freeze top row
sheet.freeze(1, 1);  // Freeze top row and first column
sheet.freeze(0, 2);  // Freeze first two columns only

unfreeze()​

Remove freeze panes.

unfreeze(): this
sheet.unfreeze();

Auto Filter​

setAutoFilter()​

Enable auto filter on a range.

setAutoFilter(range: string | RangeDefinition): this
sheet.setAutoFilter('A1:D100');

removeAutoFilter()​

Remove auto filter.

removeAutoFilter(): this

autoFilter​

Get auto filter configuration.

get autoFilter(): AutoFilter | undefined

Conditional Formatting​

addConditionalFormat()​

Add a conditional formatting rule.

addConditionalFormat(rule: ConditionalFormatRule): this

conditionalFormats​

Get all conditional formatting rules.

get conditionalFormats(): readonly ConditionalFormatRule[]

clearConditionalFormats()​

Remove all conditional formatting.

clearConditionalFormats(): this

Protection​

protect()​

Protect the sheet.

protect(options?: SheetProtection): this
interface SheetProtection {
  password?: string;
  sheet?: boolean;
  formatCells?: boolean;
  formatColumns?: boolean;
  formatRows?: boolean;
  insertColumns?: boolean;
  insertRows?: boolean;
  deleteColumns?: boolean;
  deleteRows?: boolean;
  sort?: boolean;
  autoFilter?: boolean;
  // ... more options
}
sheet.protect({
  formatCells: false,
  insertRows: true,
});

unprotect()​

Remove sheet protection.

unprotect(): this

protection / isProtected​

Get protection settings.

get protection(): SheetProtection | undefined
get isProtected(): boolean

Page Setup​

pageSetup​

Get page setup configuration.

get pageSetup(): PageSetup
interface PageSetup {
  paperSize?: number;
  orientation?: 'portrait' | 'landscape';
  scale?: number;
  fitToWidth?: number;
  fitToHeight?: number;
  margins?: {
    top?: number;
    right?: number;
    bottom?: number;
    left?: number;
    header?: number;
    footer?: number;
  };
}

setPageSetup()​

Set page setup configuration.

setPageSetup(setup: Partial<PageSetup>): this
sheet.setPageSetup({
  orientation: 'landscape',
  margins: { top: 1, bottom: 1, left: 0.75, right: 0.75 },
});

Serialization​

toJSON()​

Convert sheet to JSON.

toJSON(): Record<string, unknown>
const json = sheet.toJSON();

Example​

import { Workbook } from 'cellify';

const workbook = new Workbook();
const sheet = workbook.addSheet('Report');

// Set column widths
[15, 20, 12, 15].forEach((width, col) => {
  sheet.setColumnWidth(col, width);
});

// Add header row
const headers = ['Product', 'Description', 'Qty', 'Price'];
headers.forEach((h, col) => {
  sheet.cell(0, col).value = h;
});

// Style header
sheet.applyStyle('A1:D1', {
  font: { bold: true, color: '#FFFFFF' },
  fill: { type: 'pattern', pattern: 'solid', foregroundColor: '#059669' },
});
sheet.setRowHeight(0, 25);

// Add data
sheet.setValues(1, 0, [
  ['Widget A', 'Premium widget', 100, 29.99],
  ['Widget B', 'Standard widget', 250, 19.99],
]);

// Freeze header
sheet.freeze(1);

// Enable filter
sheet.setAutoFilter('A1:D3');

// Merge title
sheet.cell(5, 0).value = 'Total Items: 350';
sheet.mergeCells('A6:D6');