The Object Model

If you know Excel, you already know the shape of SheetXL: a workbook holds sheets, a sheet holds cells, and you reach the cells through a range. Each of those is a TypeScript interface, and this page introduces the ones you'll use every day and how to get from one to the next.

ICellRange

Represents a rectangular selection of cells, allowing you to read, write, and manipulate data within that region. Use ICellRange to access cell values, apply formatting, and perform operations on groups of cells.

A rectangular collection of ICells within a IWorksheet.

Ranges can be retrieved using either a workbook or a sheet.

// return a range via a workbook
const rangeWB:ICellRange = workbook.getRange('Sheet1!A1:E5000');

// return the range via a sheet
const rangeSheet:ICellRange = workbook.getWorksheet('Sheet1')?.getRange('A1:E5000');

ICell

Represents a single cell within a spreadsheet. It provides access to the cell's value, formatting, and other metadata. Use ICell to get or set the properties of individual cells.

A single unit of data and meta data within an ICellRange, located at a specific row and column.

Cells are always accessed via a range and can be retrieved in a few different ways.

// returns the top/left cell
const cellTopLeft:ICell = workbook.getRange('Sheet1!A1:E5000').getCell();

// returns all cells in range as a 2D array
const cellsArray:ICell[][] = workbook.getRange('Sheet1!A1:E5000').getCells();

// iterates the cells that have content, skipping empty ones
const cellsIterator:IterableIterator<ICellRange.Entry> = workbook.getRange('Sheet1!A1:E5000').entries();

IWorksheet

Represents a collection of elements such as ICellRange, ITable, and other elements contained within and visualized through a IWorksheetView.

Sheets can be retrieved using either getWorksheet() or getWorksheets() from a workbook.

// return a sheet via a workbook
const sheet:IWorksheet = workbook.getWorksheet('Sheet1');

// return all sheets via a workbook
const sheets:IWorksheetCollection = workbook.getWorksheets();

IWorkbook

Represents a collection of IWorksheets, and other shared resources.

To create a workbook model simply import the @sheetxl/sdk package and create a new instance.

// create a default workbook
const workbook:IWorkbook = new Workbook();

ICellStyle

Represents the formatting applied to a cell or range of cells, including font, color, alignment, number format, and borders.

Provides access to the combined styling information for a cell or range, including user-applied styles and dynamic styles (e.g., from tables or conditional formatting).

// Set the fill to theme color accent 1.
workbook.getRange('Sheet1!A1:D5000').getStyle().update({ fill: 'accent1' });

ICellRanges

Represents a collection of ICellRanges. This is useful when you need work with non-contiguous ranges as a single unit, such as applying the same formatting or extracting data from multiple selections.

Ranges can be retrieved similar to a single range.

const ranges:ICellRanges = workbook.getRanges('Sheet1!A1:A5000,Sheet1!C1:C5000');
// aggregate across both areas at once
const sum:number = ranges.getStats().getAggregates().sum;

IWorksheetView

The visual presentation of a specific sheet. It controls attributes like zoom level, frozen rows/columns, gridlines visibility, and the active cell selection.

Use IWorksheetView to customize how a sheet is displayed to a specific user.

// hide the row gridlines
workbook.getWorksheet('Sheet1').getView().setShowRowGridlines(false);

IWorkbookView

The visual presentation of the entire workbook. It controls workbook-level display settings.

Use IWorkbookView to customize how a sheet is displayed to a specific user.

// Hide the statusbar
workbook.getView().setShowStatusBar(false);

More Examples

Another way to see a set of examples is to use the developer console of the full demo:

Demo console

1. Open the standalone demo.
2. Open the developer tools (Ctrl+Shift+I, or ⌥⌘I on macOS).
3. In the console, type SheetXL.moreExamples().