Skip to main content

Interacting with Sheets

This section provides an overview of the primary interfaces in the SheetXL API, forming the foundation for interacting with spreadsheet data. Understanding these interfaces will aid you in creating powerful spreadsheet solutions.

The SheetXL API provides a set of TypeScript interfaces for interacting with spreadsheets programmatically. While SheetXL has many interfaces, the most commonly used are described below.

IWorkbookISheetgetSheetsICellRangegetRangeICellforEachIStylegetStyleISheetHeaderICellHeaderICellHeaderRangeICellRangegetRangeforEachforEachgetStyleScalargetValuegetRowsgetColumns

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 ISheet.

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.getSheet('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();

// returns all cells in range as a 2D array
const cellsIterator:Iterator<ICellRange.Entry> = workbook.getRange('Sheet1!A1:E5000').entries();

ISheet​

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

Sheets can be retrieved using either getSheet() or getSheets() from a workbook.

// return a sheet via a workbook
const sheet:ISheet = workbook.getSheet('Sheet1');

// return all sheets via a workbook
const sheets:ISheetCollection = workbook.getSheets();

IWorkbook​

Represents a collection of ISheets, 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();

IStyle​

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 color accent 1.
workbook.getRange('Sheet1!A1:D5000').getStyle().setFill('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 range:ICellRanges = workbook.getRanges('Sheet1!A1:A5000,Sheet1!C1:C5000').getStats().getSum();

ISheetView​

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

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

// hide the row gridlines
workbook.getSheet('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 use developer console of full demo:

Demo console​

  • Open the standalone demo at standalone demo
  • Open the developer tools (Ctl+Shift+I)
  • In the console window type SheetXL.moreExamples()

CodeSandbox​