xlsx API

This reference covers the workbook operations exposed in three places:

witan xlsx exec: call await xlsx.method(wb, ...) from the sandboxed script.
JavaScript SDK: call await wb.method(...) on a Workbook opened from the witan npm package.
Python SDK: call wb.method(...) or await wb.method(...) on Workbook / AsyncWorkbook from the witan PyPI package.

Call Shapes

witan xlsx exec report.xlsx --expr 'await xlsx.readCell(wb, "Summary!A1")'

// JavaScript SDK
await using wb = await Workbook.open("report.xlsx")
await wb.readCell("Summary!A1")

# Python SDK
with Workbook("report.xlsx") as wb:
    wb.read_cell("Summary!A1")

SDK Lifecycle

These methods manage SDK sessions. They are not callable as xlsx.* methods inside witan xlsx exec; exec opens the workbook before your script starts and persists only when the CLI is run with --save.

Method	Purpose	JavaScript	Python
Workbook.open	Open an existing workbook-backed RPC session from an SDK.	Workbook.open(path, options?)	Workbook(path, options) / AsyncWorkbook(path, options)
Workbook.save	Persist the current RPC session to disk. Not available inside `witan xlsx exec` scripts.	wb.save()	wb.save()
Workbook.close	Close the SDK RPC session. Not available inside `witan xlsx exec` scripts.	wb.close()	wb.close()

Method Summary

Workbook and sheets

Method	JavaScript SDK	Python SDK
getWorkbookProperties	wb.getWorkbookProperties()	wb.get_workbook_properties()
setWorkbookProperties	wb.setWorkbookProperties(properties: WorkbookPropertiesUpdate)	wb.set_workbook_properties(properties: WorkbookPropertiesUpdate)
listSheets	wb.listSheets()	wb.list_sheets()
addSheet	wb.addSheet(name: string)	wb.add_sheet(name: str)
deleteSheet	wb.deleteSheet(name: string)	wb.delete_sheet(name: str)
renameSheet	wb.renameSheet(oldName: string, newName: string)	wb.rename_sheet(old_name: str, new_name: str)
getSheetProperties	wb.getSheetProperties(sheet: string, options: { columns?: (number \| string)[]; rows?: number[] } = {})	wb.get_sheet_properties(sheet_name: str, columns: Sequence[int \| str] \| None = None, rows: Sequence[int] \| None = None)
setSheetProperties	wb.setSheetProperties(sheet: string, properties: SheetPropertiesUpdate)	wb.set_sheet_properties(sheet_name: str, properties: SheetPropertiesUpdate)
listDefinedNames	wb.listDefinedNames()	wb.list_defined_names()
addDefinedName	wb.addDefinedName(name: string, range: string, options: { scope?: string } = {})	wb.add_defined_name(name: str, range: str, scope: str \| None = None)
deleteDefinedName	wb.deleteDefinedName(name: string, options: { scope?: string } = {})	wb.delete_defined_name(name: str, scope: str \| None = None)

Reading

Method	JavaScript SDK	Python SDK
readCell	wb.readCell(cell: string, options: { context?: number } = {})	wb.read_cell(cell: CellRef, context: int \| None = None)
readRange	wb.readRange(range: string)	wb.read_range(range: RangeRef)
readRow	wb.readRow(sheet: string, row: number, options: { startCol?: number; endCol?: number } = {})	wb.read_row(sheet_name: str, row: int, start_col: int \| None = None, end_col: int \| None = None)
readColumn	wb.readColumn(sheet: string, col: number \| string, options: { startRow?: number; endRow?: number } = {})	wb.read_column(sheet_name: str, col: int \| str, start_row: int \| None = None, end_row: int \| None = None)
readRangeTsv	wb.readRangeTsv(range: string, options: { includeEmpty?: boolean; includeFormulas?: boolean } = {})	wb.read_range_tsv(range: RangeRef, include_empty: bool \| None = None, include_formulas: bool \| None = None)
readRowTsv	wb.readRowTsv(sheet: string, row: number, options: { startCol?: number; endCol?: number; includeEmpty?: boolean; includeFormulas?: boolean; } = {})	wb.read_row_tsv(sheet_name: str, row: int, start_col: int \| None = None, end_col: int \| None = None, include_empty: bool \| None = None, include_formulas: bool \| None = None)
readColumnTsv	wb.readColumnTsv(sheet: string, col: number \| string, options: { startRow?: number; endRow?: number; includeEmpty?: boolean; includeFormulas?: boolean; } = {})	wb.read_column_tsv(sheet_name: str, col: int \| str, start_row: int \| None = None, end_row: int \| None = None, include_empty: bool \| None = None, include_formulas: bool \| None = None)

Search and discovery

Method	JavaScript SDK	Python SDK
findCells	wb.findCells(matcher: Matcher, options: { in?: string; context?: number; limit?: number; offset?: number; formulas?: boolean; } = {})	wb.find_cells(matcher: Matcher, in_: RangeRef \| None = None, context: int = 2, limit: int = 20, offset: int = 0, formulas: bool \| None = None)
findRows	wb.findRows(matcher: Matcher, options: { in?: string; context?: number; limit?: number; offset?: number; } = {})	wb.find_rows(matcher: Matcher, in_: RangeRef \| None = None, context: int \| None = None, limit: int = 20, offset: int = 0)
findAndReplace	wb.findAndReplace(find: ReplaceMatcher, replace: string, options: { in?: string; matchCase?: boolean; wholeCell?: boolean; inFormulas?: boolean; limit?: number; } = {})	wb.find_and_replace(find: ReplaceMatcher, replace: str, in_: RangeRef \| None = None, match_case: bool \| None = None, whole_cell: bool \| None = None, in_formulas: bool \| None = None, limit: int \| None = None)
describeSheet	wb.describeSheet(sheet: string)	wb.describe_sheet(sheet_name: str)
tableLookup	wb.tableLookup(table: string, rowLabel: string \| number \| boolean, columnLabel: string \| number \| boolean)	wb.table_lookup(table: str, row_label: str \| int \| float \| bool, column_label: str \| int \| float \| bool)

Tables, data tables, and charts

Method	JavaScript SDK	Python SDK
getListObject	wb.getListObject(name: string)	wb.get_list_object(name: str)
addListObject	wb.addListObject(sheet: string, listObject: ListObjectSpec)	wb.add_list_object(sheet_name: str, list_object: ListObjectSpec)
setListObject	wb.setListObject(name: string, listObject: ListObjectUpdate)	wb.set_list_object(name: str, list_object: ListObjectUpdate)
deleteListObject	wb.deleteListObject(name: string)	wb.delete_list_object(name: str)
getDataTable	wb.getDataTable(address: string)	wb.get_data_table(address: str)
addDataTable	wb.addDataTable(sheet: string, dataTable: DataTableSpec)	wb.add_data_table(sheet_name: str, data_table: DataTableSpec)
deleteDataTable	wb.deleteDataTable(address: string)	wb.delete_data_table(address: str)
listCharts	wb.listCharts(options: { sheet?: string } = {})	wb.list_charts(sheet: str \| None = None)
getChart	wb.getChart(sheet: string, name: string)	wb.get_chart(sheet: str, name: str)
addChart	wb.addChart(sheet: string, chart: ChartSpec)	wb.add_chart(sheet: str, chart: ChartSpec)
setChart	wb.setChart(sheet: string, name: string, chart: ChartSpec)	wb.set_chart(sheet: str, name: str, chart: ChartSpec)
deleteChart	wb.deleteChart(sheet: string, name: string)	wb.delete_chart(sheet: str, name: str)

Images and drawings

Method	JavaScript SDK	Python SDK
listImages	wb.listImages(options: { sheet?: string } = {})	wb.list_images(sheet: str \| None = None)
getImage	wb.getImage(sheet: string, selector: ImageSelector)	wb.get_image(sheet: str, name: str \| None = None, id: int \| None = None)
addImage	wb.addImage(sheet: string, image: ImageSpec)	wb.add_image(sheet: str, image: ImageSpec)
setImage	wb.setImage(sheet: string, selector: ImageSelector, image: ImageUpdate)	wb.set_image(sheet: str, image: ImageUpdate, name: str \| None = None, id: int \| None = None)
deleteImage	wb.deleteImage(sheet: string, selector: ImageSelector)	wb.delete_image(sheet: str, name: str \| None = None, id: int \| None = None)

Writing and structure

Method	JavaScript SDK	Python SDK
setCells	wb.setCells(cells: CellAssignment[], options: { validationMode?: SetCellsValidationMode } = {})	wb.set_cells(cells: Sequence[JsonMapping], validation_mode: SetCellsValidationMode \| None = None)
copyRange	wb.copyRange(source: string, destination: string, options: { pasteType?: PasteType } = {})	wb.copy_range(source: RangeRef, destination: CellRef, paste_type: Literal["all", "values", "formulas", "formats"] \| None = None)
scaleRange	wb.scaleRange(range: string, factor: number, options: { skipFormulas?: boolean } = {})	wb.scale_range(range: RangeRef, factor: float, skip_formulas: bool = True)
insertRowAfter	wb.insertRowAfter(sheet: string, row: number, count: number = 1)	wb.insert_row_after(sheet_name: str, row: int, count: int = 1)
deleteRows	wb.deleteRows(sheet: string, row: number, count: number = 1)	wb.delete_rows(sheet_name: str, row: int, count: int = 1)
insertColumnAfter	wb.insertColumnAfter(sheet: string, column: number \| string, count: number = 1)	wb.insert_column_after(sheet_name: str, column: int \| str, count: int = 1)
deleteColumns	wb.deleteColumns(sheet: string, column: number \| string, count: number = 1)	wb.delete_columns(sheet_name: str, column: int \| str, count: int = 1)
setRowProperties	wb.setRowProperties(sheet: string, fromRow: number, toRow: number, properties: RowProperties)	wb.set_row_properties(sheet_name: str, from_row: int, to_row: int, properties: RowProperties)
setColumnProperties	wb.setColumnProperties(sheet: string, fromCol: number \| string, toCol: number \| string, properties: ColumnProperties)	wb.set_column_properties(sheet_name: str, from_col: int \| str, to_col: int \| str, properties: ColumnProperties)
autoFitColumns	wb.autoFitColumns(sheet: string, columns?: (number \| string)[], options: { minWidth?: number; maxWidth?: number; padding?: number } = {})	wb.auto_fit_columns(sheet_name: str, columns: Sequence[int \| str] \| None = None, min_width: float \| None = None, max_width: float \| None = None, padding: float \| None = None)
autoFitRows	wb.autoFitRows(sheet: string, rows?: number[], options: { minHeight?: number; maxHeight?: number } = {})	wb.auto_fit_rows(sheet_name: str, rows: Sequence[int] \| None = None, min_height: float \| None = None, max_height: float \| None = None)
sortRange	wb.sortRange(range: string, keys: SortKey[], options: { hasHeader?: boolean } = {})	wb.sort_range(range: RangeRef, keys: Sequence[JsonMapping], has_header: bool \| None = None)

Styles and formatting

Method	JavaScript SDK	Python SDK
setStyle	wb.setStyle(target: string, style: Style)	wb.set_style(target: CellRef \| RangeRef, style: Style)
getConditionalFormatting	wb.getConditionalFormatting(sheet: string)	wb.get_conditional_formatting(sheet_name: str)
setConditionalFormatting	wb.setConditionalFormatting(sheet: string, rules: ConditionalFormattingRule[], options: { clear?: boolean } = {})	wb.set_conditional_formatting(sheet_name: str, rules: Sequence[ConditionalFormattingRule], clear: bool \| None = None)
removeConditionalFormatting	wb.removeConditionalFormatting(sheet: string, indices: number[])	wb.remove_conditional_formatting(sheet_name: str, indices: Sequence[int])
getStyle	wb.getStyle(cell: string)	wb.get_style(cell: CellRef)

Data validation

Method	JavaScript SDK	Python SDK
getDataValidations	wb.getDataValidations(options: { sheet?: string; address?: string } = {})	wb.get_data_validations(sheet: str \| None = None, address: str \| None = None)
setDataValidations	wb.setDataValidations(sheet: string, rules: DataValidationSpec[], options: { clear?: boolean } = {})	wb.set_data_validations(sheet_name: str, rules: Sequence[DataValidationSpec], clear: bool \| None = None)
removeDataValidations	wb.removeDataValidations(sheet: string, target: { indices: number[] } \| { address: string })	wb.remove_data_validations(sheet_name: str, indices: Sequence[int] \| None = None, address: str \| None = None)

Formulas and dependencies

Method	JavaScript SDK	Python SDK
evaluateFormulas	wb.evaluateFormulas(sheet: string, formulas: string[])	wb.evaluate_formulas(sheet: str, formulas: Sequence[str])
evaluateFormula	wb.evaluateFormula(sheet: string, formula: string)	wb.evaluate_formula(sheet: str, formula: str)
getCellPrecedents	wb.getCellPrecedents(address: string, depth: number \| typeof Infinity = 1)	wb.get_cell_precedents(address: CellRef, depth: int \| float = 1)
getCellDependents	wb.getCellDependents(address: string, depth: number \| typeof Infinity = 1)	wb.get_cell_dependents(address: CellRef, depth: int \| float = 1)
traceToInputs	wb.traceToInputs(address: string)	wb.trace_to_inputs(cell: CellRef)
traceToOutputs	wb.traceToOutputs(address: string)	wb.trace_to_outputs(cell: CellRef)
sweepInputs	wb.sweepInputs(inputs: SweepInput[], outputs: string[], options: { mode?: SweepMode; includeStats?: boolean } = {})	wb.sweep_inputs(inputs: Sequence[JsonMapping], outputs: Sequence[str \| CellRef], mode: Literal["cartesian", "parallel"] \| None = None, include_stats: bool \| None = None)

Verification and rendering

Method	JavaScript SDK	Python SDK
lint	wb.lint(options: { rangeAddresses?: string[]; skipRuleIds?: string[]; onlyRuleIds?: string[]; } = {})	wb.lint(range_addresses: Sequence[str] \| None = None, skip_rule_ids: Sequence[str] \| None = None, only_rule_ids: Sequence[str] \| None = None)
previewStyles	wb.previewStyles(range: string)	wb.preview_styles(range: RangeRef)

Utilities

Method	JavaScript SDK	Python SDK
reduceAddresses	wb.reduceAddresses(addresses: string[])	wb.reduce_addresses(addresses: Sequence[CellRef \| RangeRef])

Workbook and sheets

getWorkbookProperties

Get workbook-level properties.

Surface	Call
Exec	`await xlsx.getWorkbookProperties(wb)`
JavaScript SDK	`wb.getWorkbookProperties()`
Python SDK	`wb.get_workbook_properties()`

Signature

async function getWorkbookProperties(wb: WorkbookContext): Promise<{
  activeSheetIndex: number;
  defaultFont: {
    name: string;
    size: number;
  };
  metadata?: | {
      author?: string | null;
      title?: string | null;
      subject?: string | null;
      company?: string | null;
      created?: string | null;
      modified?: string | null;
    }
  | null;
  themeColors?: | {
      dark1: string;
      light1: string;
      dark2: string;
      light2: string;
      accent1: string;
      accent2: string;
      accent3: string;
      accent4: string;
      accent5: string;
      accent6: string;
      hyperlink: string;
      followedHyperlink: string;
      majorFont?: string | null;
      minorFont?: string | null;
    }
  | null;
  iterativeCalculation: {
    enabled: boolean;
    maxIterations: number;
    maxChange: number;
  };
}>

setWorkbookProperties

Set workbook-level properties.

Surface	Call
Exec	`await xlsx.setWorkbookProperties(wb, ...)`
JavaScript SDK	`wb.setWorkbookProperties(properties: WorkbookPropertiesUpdate)`
Python SDK	`wb.set_workbook_properties(properties: WorkbookPropertiesUpdate)`

Signature

async function setWorkbookProperties(wb: WorkbookContext, properties: WorkbookPropertiesUpdate): Promise<void>

listSheets

List all sheets in the workbook.

Surface	Call
Exec	`await xlsx.listSheets(wb)`
JavaScript SDK	`wb.listSheets()`
Python SDK	`wb.list_sheets()`

Signature

async function listSheets(wb: WorkbookContext): Promise<{
  address: string;
  rows: number;
  cols: number;
  sheet: string;
  hidden?: boolean;
  printArea?: string;
  listObjects?: string[];
  dataTables?: string[];
  precedents?: string[];
  dependents?: string[];
}[]>

addSheet

Add a new sheet to the workbook. @param name - Name for the new sheet @returns The name of the created sheet

Surface	Call
Exec	`await xlsx.addSheet(wb, ...)`
JavaScript SDK	`wb.addSheet(name: string)`
Python SDK	`wb.add_sheet(name: str)`

Signature

async function addSheet(wb: WorkbookContext, name: string): Promise<string>

deleteSheet

Delete a sheet from the workbook. @param name - Name of the sheet to delete

Surface	Call
Exec	`await xlsx.deleteSheet(wb, ...)`
JavaScript SDK	`wb.deleteSheet(name: string)`
Python SDK	`wb.delete_sheet(name: str)`

Signature

async function deleteSheet(wb: WorkbookContext, name: string): Promise<void>

renameSheet

Rename a sheet. @param oldName - Current name of the sheet @param newName - New name for the sheet

Surface	Call
Exec	`await xlsx.renameSheet(wb, ...)`
JavaScript SDK	`wb.renameSheet(oldName: string, newName: string)`
Python SDK	`wb.rename_sheet(old_name: str, new_name: str)`

Signature

async function renameSheet(wb: WorkbookContext, oldName: string, newName: string): Promise<void>

getSheetProperties

Get properties of a sheet. @param sheet - Sheet name @param options - Filter options for columns/rows

Surface	Call
Exec	`await xlsx.getSheetProperties(wb, ...)`
JavaScript SDK	`wb.getSheetProperties(sheet: string, options: { columns?: (number \| string)[]; rows?: number[] } = {})`
Python SDK	`wb.get_sheet_properties(sheet_name: str, columns: Sequence[int \| str] \| None = None, rows: Sequence[int] \| None = None)`

Signature

async function getSheetProperties(wb: WorkbookContext, sheet: string, options: { columns?: (number | string)[]; rows?: number[] } = {}): Promise<{
  visibility: 'visible' | 'hidden' | 'veryHidden';
  view: {
    showGridLines: boolean;
    zoomScale: number;
    freezeRows: number;
    freezeColumns: number;
  };
  outline: {
    summaryRowsBelow: boolean;
    summaryColumnsRight: boolean;
    showSymbols: boolean;
  };
  format: {
    defaultRowHeight: number;
    defaultColWidth: number;
    font?: | {
        name?: string | null;
        size?: number | null;
      }
    | null;
  };
  columns: {
    [key: string]: {
    col: string;
    width: number;
    hidden?: boolean;
    outlineLevel?: number;
    collapsed?: boolean;
  };
  };
  rows: {
    [key: number]: {
    row: number;
    height: number;
    hidden?: boolean;
    outlineLevel?: number;
    collapsed?: boolean;
  };
  };
  merges?: string[] | null;
}>

setSheetProperties

Set properties of a sheet. @param sheet - Sheet name @param properties - Properties to set

Surface	Call
Exec	`await xlsx.setSheetProperties(wb, ...)`
JavaScript SDK	`wb.setSheetProperties(sheet: string, properties: SheetPropertiesUpdate)`
Python SDK	`wb.set_sheet_properties(sheet_name: str, properties: SheetPropertiesUpdate)`

Signature

async function setSheetProperties(wb: WorkbookContext, sheet: string, properties: SheetPropertiesUpdate): Promise<void>

listDefinedNames

List all defined names in the workbook.

Surface	Call
Exec	`await xlsx.listDefinedNames(wb)`
JavaScript SDK	`wb.listDefinedNames()`
Python SDK	`wb.list_defined_names()`

Signature

async function listDefinedNames(wb: WorkbookContext): Promise<{
  name: string;
  range: string;
  scope: string | null;
}[]>

addDefinedName

Add a defined name to the workbook.

@param name - Name to define @param range - Range address the name refers to @param options - Options including optional scope @returns The created defined name

Surface	Call
Exec	`await xlsx.addDefinedName(wb, ...)`
JavaScript SDK	`wb.addDefinedName(name: string, range: string, options: { scope?: string } = {})`
Python SDK	`wb.add_defined_name(name: str, range: str, scope: str \| None = None)`

Signature

async function addDefinedName(wb: WorkbookContext, name: string, range: string, options: { scope?: string } = {}): Promise<{
  name: string;
  range: string;
  scope: string | null;
}>

deleteDefinedName

Delete a defined name from the workbook.

@param name - Name to delete @param options - Options including optional scope @returns The deleted defined name

Surface	Call
Exec	`await xlsx.deleteDefinedName(wb, ...)`
JavaScript SDK	`wb.deleteDefinedName(name: string, options: { scope?: string } = {})`
Python SDK	`wb.delete_defined_name(name: str, scope: str \| None = None)`

Signature

async function deleteDefinedName(wb: WorkbookContext, name: string, options: { scope?: string } = {}): Promise<{
  name: string;
  range: string;
  scope: string | null;
}>

Reading

readCell

Read a single cell value. This is a composite operation that calls readRange and extracts the first cell.

@param cell - Cell address (e.g., "Sheet1!A1" or "A1") @param options - Read options @returns The cell value

Surface	Call
Exec	`await xlsx.readCell(wb, ...)`
JavaScript SDK	`wb.readCell(cell: string, options: { context?: number } = {})`
Python SDK	`wb.read_cell(cell: CellRef, context: int \| None = None)`

Signature

async function readCell(wb: WorkbookContext, cell: string, options: { context?: number } = {}): Promise<{
  address: string;
  sheet: string;
  row: number;
  col: number;
  colLetter: string;
  value: unknown;
  formula?: string;
  type: 'string' | 'number' | 'bool' | 'date' | 'error' | 'blank';
  text: string;
  format?: string;
  numberType?: 'currency' | 'percent' | 'fraction' | 'exponential' | 'date' | 'text' | 'number';
  visibility: 'visible' | 'outsidePrintArea' | 'collapsed' | 'hidden';
  context?: string;
  note?: {
    author: string;
    text: string;
  };
  link?: {
    type: 'internal' | 'external';
    target: string;
    tooltip?: string;
  };
  thread?: {
    resolved: boolean;
    comments: {
      authorId: string;
      text: string;
      createdAt: string;
    }[];
  };
}>

readRange

Read a range of cells.

@param range - Range address (e.g., "Sheet1!A1 ") @returns 2D array of cell values

Surface	Call
Exec	`await xlsx.readRange(wb, ...)`
JavaScript SDK	`wb.readRange(range: string)`
Python SDK	`wb.read_range(range: RangeRef)`

Signature

async function readRange(wb: WorkbookContext, range: string): Promise<{
  address: string;
  sheet: string;
  row: number;
  col: number;
  colLetter: string;
  value: unknown;
  formula?: string;
  type: 'string' | 'number' | 'bool' | 'date' | 'error' | 'blank';
  text: string;
  format?: string;
  numberType?: 'currency' | 'percent' | 'fraction' | 'exponential' | 'date' | 'text' | 'number';
  visibility: 'visible' | 'outsidePrintArea' | 'collapsed' | 'hidden';
  context?: string;
  note?: {
    author: string;
    text: string;
  };
  link?: {
    type: 'internal' | 'external';
    target: string;
    tooltip?: string;
  };
  thread?: {
    resolved: boolean;
    comments: ThreadComment[];
  };
}[][]>

readRow

Read a row of cells.

@param sheet - Sheet name @param row - Row number (1-based) @param options - Read options @returns Array of cell values

Surface	Call
Exec	`await xlsx.readRow(wb, ...)`
JavaScript SDK	`wb.readRow(sheet: string, row: number, options: { startCol?: number; endCol?: number } = {})`
Python SDK	`wb.read_row(sheet_name: str, row: int, start_col: int \| None = None, end_col: int \| None = None)`

Signature

async function readRow(wb: WorkbookContext, sheet: string, row: number, options: { startCol?: number; endCol?: number } = {}): Promise<{
  address: string;
  sheet: string;
  row: number;
  col: number;
  colLetter: string;
  value: unknown;
  formula?: string;
  type: 'string' | 'number' | 'bool' | 'date' | 'error' | 'blank';
  text: string;
  format?: string;
  numberType?: 'currency' | 'percent' | 'fraction' | 'exponential' | 'date' | 'text' | 'number';
  visibility: 'visible' | 'outsidePrintArea' | 'collapsed' | 'hidden';
  context?: string;
  note?: {
    author: string;
    text: string;
  };
  link?: {
    type: 'internal' | 'external';
    target: string;
    tooltip?: string;
  };
  thread?: {
    resolved: boolean;
    comments: {
      authorId: string;
      text: string;
      createdAt: string;
    }[];
  };
}[]>

readColumn

Read a column of cells.

@param sheet - Sheet name @param col - Column number (1-based) or letter (e.g., "A") @param options - Read options @returns Array of cell values

Surface	Call
Exec	`await xlsx.readColumn(wb, ...)`
JavaScript SDK	`wb.readColumn(sheet: string, col: number \| string, options: { startRow?: number; endRow?: number } = {})`
Python SDK	`wb.read_column(sheet_name: str, col: int \| str, start_row: int \| None = None, end_row: int \| None = None)`

Signature

async function readColumn(wb: WorkbookContext, sheet: string, col: number | string, options: { startRow?: number; endRow?: number } = {}): Promise<{
  address: string;
  sheet: string;
  row: number;
  col: number;
  colLetter: string;
  value: unknown;
  formula?: string;
  type: 'string' | 'number' | 'bool' | 'date' | 'error' | 'blank';
  text: string;
  format?: string;
  numberType?: 'currency' | 'percent' | 'fraction' | 'exponential' | 'date' | 'text' | 'number';
  visibility: 'visible' | 'outsidePrintArea' | 'collapsed' | 'hidden';
  context?: string;
  note?: {
    author: string;
    text: string;
  };
  link?: {
    type: 'internal' | 'external';
    target: string;
    tooltip?: string;
  };
  thread?: {
    resolved: boolean;
    comments: {
      authorId: string;
      text: string;
      createdAt: string;
    }[];
  };
}[]>

readRangeTsv

Read a range as tab-separated values.

@param range - Range address @param options - Read options @returns TSV string

Surface	Call
Exec	`await xlsx.readRangeTsv(wb, ...)`
JavaScript SDK	`wb.readRangeTsv(range: string, options: { includeEmpty?: boolean; includeFormulas?: boolean } = {})`
Python SDK	`wb.read_range_tsv(range: RangeRef, include_empty: bool \| None = None, include_formulas: bool \| None = None)`

Signature

async function readRangeTsv(wb: WorkbookContext, range: string, options: { includeEmpty?: boolean; includeFormulas?: boolean } = {}): Promise<string>

readRowTsv

Read a row as tab-separated values.

@param sheet - Sheet name @param row - Row number (1-based) @param options - Read options @returns TSV string

Surface	Call
Exec	`await xlsx.readRowTsv(wb, ...)`
JavaScript SDK	`wb.readRowTsv(sheet: string, row: number, options: { startCol?: number; endCol?: number; includeEmpty?: boolean; includeFormulas?: boolean; } = {})`
Python SDK	`wb.read_row_tsv(sheet_name: str, row: int, start_col: int \| None = None, end_col: int \| None = None, include_empty: bool \| None = None, include_formulas: bool \| None = None)`

Signature

async function readRowTsv(wb: WorkbookContext, sheet: string, row: number, options: { startCol?: number; endCol?: number; includeEmpty?: boolean; includeFormulas?: boolean; } = {}): Promise<string>

readColumnTsv

Read a column as tab-separated values.

@param sheet - Sheet name @param col - Column number (1-based) or letter @param options - Read options @returns TSV string

Surface	Call
Exec	`await xlsx.readColumnTsv(wb, ...)`
JavaScript SDK	`wb.readColumnTsv(sheet: string, col: number \| string, options: { startRow?: number; endRow?: number; includeEmpty?: boolean; includeFormulas?: boolean; } = {})`
Python SDK	`wb.read_column_tsv(sheet_name: str, col: int \| str, start_row: int \| None = None, end_row: int \| None = None, include_empty: bool \| None = None, include_formulas: bool \| None = None)`

Signature

async function readColumnTsv(wb: WorkbookContext, sheet: string, col: number | string, options: { startRow?: number; endRow?: number; includeEmpty?: boolean; includeFormulas?: boolean; } = {}): Promise<string>

Search and discovery

findCells

Find cells matching a pattern.

@param matcher - String, number, boolean, RegExp, or array of strings/RegExps @param options - Search options @returns Array of matching cells

Surface	Call
Exec	`await xlsx.findCells(wb, ...)`
JavaScript SDK	`wb.findCells(matcher: Matcher, options: { in?: string; context?: number; limit?: number; offset?: number; formulas?: boolean; } = {})`
Python SDK	`wb.find_cells(matcher: Matcher, in_: RangeRef \| None = None, context: int = 2, limit: int = 20, offset: int = 0, formulas: bool \| None = None)`

Signature

async function findCells(wb: WorkbookContext, matcher: Matcher, options: { in?: string; context?: number; limit?: number; offset?: number; formulas?: boolean; } = {}): Promise<{
  type: 'cell';
  address: string;
  value: unknown;
  text: string;
  formula?: string;
  row: number;
  col: number;
  colLetter: string;
  sheet: string;
  visibility: 'visible' | 'outsidePrintArea' | 'collapsed' | 'hidden';
  context?: string;
  role: string;
}[]>

findRows

Find rows containing cells matching a pattern.

@param matcher - String, number, boolean, RegExp, or array of strings/RegExps @param options - Search options @returns Array of matching rows

Surface	Call
Exec	`await xlsx.findRows(wb, ...)`
JavaScript SDK	`wb.findRows(matcher: Matcher, options: { in?: string; context?: number; limit?: number; offset?: number; } = {})`
Python SDK	`wb.find_rows(matcher: Matcher, in_: RangeRef \| None = None, context: int \| None = None, limit: int = 20, offset: int = 0)`

Signature

async function findRows(wb: WorkbookContext, matcher: Matcher, options: { in?: string; context?: number; limit?: number; offset?: number; } = {}): Promise<{
  type: 'row';
  row: number;
  sheet: string;
  matchedAt: string;
  range: string;
  tsv: string;
  visibility: 'visible' | 'outsidePrintArea' | 'collapsed' | 'hidden';
  context?: string;
}[]>

findAndReplace

Find and replace text in cells.

@param find - String or RegExp to find @param replace - Replacement string @param options - Find and replace options @returns Result with count of replacements made

Surface	Call
Exec	`await xlsx.findAndReplace(wb, ...)`
JavaScript SDK	`wb.findAndReplace(find: ReplaceMatcher, replace: string, options: { in?: string; matchCase?: boolean; wholeCell?: boolean; inFormulas?: boolean; limit?: number; } = {})`
Python SDK	`wb.find_and_replace(find: ReplaceMatcher, replace: str, in_: RangeRef \| None = None, match_case: bool \| None = None, whole_cell: bool \| None = None, in_formulas: bool \| None = None, limit: int \| None = None)`

Signature

async function findAndReplace(wb: WorkbookContext, find: ReplaceMatcher, replace: string, options: { in?: string; matchCase?: boolean; wholeCell?: boolean; inFormulas?: boolean; limit?: number; } = {}): Promise<{
  replaced: number;
  cells: string[];
  errors: {
    code: string;
    address: string;
    detail?: string;
    formula?: string;
  }[];
}>

describeSheet

Get a description of a sheet's structure.

@param sheet - Sheet name @returns Sheet description

Surface	Call
Exec	`await xlsx.describeSheet(wb, ...)`
JavaScript SDK	`wb.describeSheet(sheet: string)`
Python SDK	`wb.describe_sheet(sheet_name: str)`

Signature

async function describeSheet(wb: WorkbookContext, sheet: string): Promise<{
  tables: {
    [key: string]: {
    address: string;
    headerRows: string;
    headerCols?: string | null;
    tableName?: string | null;
  };
  };
  structure: string;
}>

tableLookup

Look up a value in a table by row and column labels.

@param table - Table name or address @param rowLabel - Row label to find @param columnLabel - Column label to find @returns Array of lookup results

Surface	Call
Exec	`await xlsx.tableLookup(wb, ...)`
JavaScript SDK	`wb.tableLookup(table: string, rowLabel: string \| number \| boolean, columnLabel: string \| number \| boolean)`
Python SDK	`wb.table_lookup(table: str, row_label: str \| int \| float \| bool, column_label: str \| int \| float \| bool)`

Signature

async function tableLookup(wb: WorkbookContext, table: string, rowLabel: string | number | boolean, columnLabel: string | number | boolean): Promise<{
  address: string;
  value: unknown;
  text: string;
  row: number;
  col: number;
  colLetter: string;
  sheet: string;
  visibility: 'visible' | 'outsidePrintArea' | 'collapsed' | 'hidden';
  rowLabelFoundAt: string;
  rowLabelFound: string;
  columnLabelFoundAt: string;
  columnLabelFound: string;
}[]>

Tables, data tables, and charts

getListObject

Get a list object (table) by name.

@param name - Name of the list object @returns The list object

Surface	Call
Exec	`await xlsx.getListObject(wb, ...)`
JavaScript SDK	`wb.getListObject(name: string)`
Python SDK	`wb.get_list_object(name: str)`

Signature

async function getListObject(wb: WorkbookContext, name: string): Promise<{
  name: string;
  sheet: string;
  ref: string;
  showHeaderRow: boolean;
  showTotalsRow: boolean;
  showAutoFilter: boolean;
  tableStyleName: string | null;
  showFirstColumn: boolean;
  showLastColumn: boolean;
  showRowStripes: boolean;
  showColumnStripes: boolean;
  headerRowRange: string | null;
  dataRange: string | null;
  totalsRowRange: string | null;
  columns: {
    name: string;
    totalsRowFunction?: string | null;
    totalsRowLabel?: string | null;
    totalsRowFormula?: string | null;
    calculatedColumnFormula?: string | null;
  }[];
}>

addListObject

Add a list object (table) to a sheet.

@param sheet - Sheet name @param listObject - List object specification @returns Mutation result with the created list object

Surface	Call
Exec	`await xlsx.addListObject(wb, ...)`
JavaScript SDK	`wb.addListObject(sheet: string, listObject: ListObjectSpec)`
Python SDK	`wb.add_list_object(sheet_name: str, list_object: ListObjectSpec)`

Signature

async function addListObject(wb: WorkbookContext, sheet: string, listObject: ListObjectSpec): Promise<{
  touched: {
    [key: string]: string;
  };
  changed: string[];
  errors: {
    code: string;
    address: string;
    detail?: string;
    formula?: string;
  }[];
  invalidatedTiles: {
    sheet: string;
    tileRow: number;
    tileCol: number;
  }[];
  updatedSheets: {
    name: string;
    usedRange: | {
        startRow: number;
        startCol: number;
        endRow: number;
        endCol: number;
      }
    | null;
    tileRowCount: number;
    tileColCount: number;
  }[];
  listObject: {
    name: string;
    sheet: string;
    ref: string;
    showHeaderRow: boolean;
    showTotalsRow: boolean;
    showAutoFilter: boolean;
    tableStyleName: string | null;
    showFirstColumn: boolean;
    showLastColumn: boolean;
    showRowStripes: boolean;
    showColumnStripes: boolean;
    headerRowRange: string | null;
    dataRange: string | null;
    totalsRowRange: string | null;
    columns: {
      name: string;
      totalsRowFunction?: string | null;
      totalsRowLabel?: string | null;
      totalsRowFormula?: string | null;
      calculatedColumnFormula?: string | null;
    }[];
  };
}>

setListObject

Update a list object (table).

@param name - Name of the list object to update @param listObject - Updated list object properties @returns Mutation result with the updated list object

Surface	Call
Exec	`await xlsx.setListObject(wb, ...)`
JavaScript SDK	`wb.setListObject(name: string, listObject: ListObjectUpdate)`
Python SDK	`wb.set_list_object(name: str, list_object: ListObjectUpdate)`

Signature

async function setListObject(wb: WorkbookContext, name: string, listObject: ListObjectUpdate): Promise<{
  touched: {
    [key: string]: string;
  };
  changed: string[];
  errors: {
    code: string;
    address: string;
    detail?: string;
    formula?: string;
  }[];
  invalidatedTiles: {
    sheet: string;
    tileRow: number;
    tileCol: number;
  }[];
  updatedSheets: {
    name: string;
    usedRange: | {
        startRow: number;
        startCol: number;
        endRow: number;
        endCol: number;
      }
    | null;
    tileRowCount: number;
    tileColCount: number;
  }[];
  listObject: {
    name: string;
    sheet: string;
    ref: string;
    showHeaderRow: boolean;
    showTotalsRow: boolean;
    showAutoFilter: boolean;
    tableStyleName: string | null;
    showFirstColumn: boolean;
    showLastColumn: boolean;
    showRowStripes: boolean;
    showColumnStripes: boolean;
    headerRowRange: string | null;
    dataRange: string | null;
    totalsRowRange: string | null;
    columns: {
      name: string;
      totalsRowFunction?: string | null;
      totalsRowLabel?: string | null;
      totalsRowFormula?: string | null;
      calculatedColumnFormula?: string | null;
    }[];
  };
}>

deleteListObject

Delete a list object (table).

@param name - Name of the list object to delete @returns Write result

Surface	Call
Exec	`await xlsx.deleteListObject(wb, ...)`
JavaScript SDK	`wb.deleteListObject(name: string)`
Python SDK	`wb.delete_list_object(name: str)`

Signature

async function deleteListObject(wb: WorkbookContext, name: string): Promise<{
  touched: {
    [key: string]: string;
  };
  changed: string[];
  errors: {
    code: string;
    address: string;
    detail?: string;
    formula?: string;
  }[];
  invalidatedTiles: {
    sheet: string;
    tileRow: number;
    tileCol: number;
  }[];
  updatedSheets: {
    name: string;
    usedRange: | {
        startRow: number;
        startCol: number;
        endRow: number;
        endCol: number;
      }
    | null;
    tileRowCount: number;
    tileColCount: number;
  }[];
}>

getDataTable

Get a data table by address.

@param address - Address of the data table @returns The data table

Surface	Call
Exec	`await xlsx.getDataTable(wb, ...)`
JavaScript SDK	`wb.getDataTable(address: string)`
Python SDK	`wb.get_data_table(address: str)`

Signature

async function getDataTable(wb: WorkbookContext, address: string): Promise<| {
    type: 'oneVariableColumn';
    sheet: string;
    ref: string;
    dataTableRange: string;
    rowInputCell: null;
    columnInputCell: string;
    inputValues: string | number | boolean | null[];
    rowInputValues: null;
    columnInputValues: null;
    formulas: {
      formula: string;
    }[];
    formula: null;
  }
| {
    type: 'oneVariableRow';
    sheet: string;
    ref: string;
    dataTableRange: string;
    rowInputCell: string;
    columnInputCell: null;
    inputValues: string | number | boolean | null[];
    rowInputValues: null;
    columnInputValues: null;
    formulas: {
      formula: string;
    }[];
    formula: null;
  }
| {
    type: 'twoVariable';
    sheet: string;
    ref: string;
    dataTableRange: string;
    rowInputCell: string;
    columnInputCell: string;
    inputValues: null;
    rowInputValues: string | number | boolean | null[];
    columnInputValues: string | number | boolean | null[];
    formulas: null;
    formula: string;
  }>

addDataTable

Add a data table to a sheet.

@param sheet - Sheet name @param dataTable - Data table specification @returns Mutation result with the created data table

Surface	Call
Exec	`await xlsx.addDataTable(wb, ...)`
JavaScript SDK	`wb.addDataTable(sheet: string, dataTable: DataTableSpec)`
Python SDK	`wb.add_data_table(sheet_name: str, data_table: DataTableSpec)`

Signature

async function addDataTable(wb: WorkbookContext, sheet: string, dataTable: DataTableSpec): Promise<{
  touched: {
    [key: string]: string;
  };
  changed: string[];
  errors: {
    code: string;
    address: string;
    detail?: string;
    formula?: string;
  }[];
  invalidatedTiles: {
    sheet: string;
    tileRow: number;
    tileCol: number;
  }[];
  updatedSheets: {
    name: string;
    usedRange: | {
        startRow: number;
        startCol: number;
        endRow: number;
        endCol: number;
      }
    | null;
    tileRowCount: number;
    tileColCount: number;
  }[];
  dataTable: | {
      type: 'oneVariableColumn';
      sheet: string;
      ref: string;
      dataTableRange: string;
      rowInputCell: null;
      columnInputCell: string;
      inputValues: string | number | boolean | null[];
      rowInputValues: null;
      columnInputValues: null;
      formulas: {
        formula: string;
      }[];
      formula: null;
    }
  | {
      type: 'oneVariableRow';
      sheet: string;
      ref: string;
      dataTableRange: string;
      rowInputCell: string;
      columnInputCell: null;
      inputValues: string | number | boolean | null[];
      rowInputValues: null;
      columnInputValues: null;
      formulas: {
        formula: string;
      }[];
      formula: null;
    }
  | {
      type: 'twoVariable';
      sheet: string;
      ref: string;
      dataTableRange: string;
      rowInputCell: string;
      columnInputCell: string;
      inputValues: null;
      rowInputValues: string | number | boolean | null[];
      columnInputValues: string | number | boolean | null[];
      formulas: null;
      formula: string;
    };
}>

deleteDataTable

Delete a data table.

@param address - Address of the data table to delete @returns Write result

Surface	Call
Exec	`await xlsx.deleteDataTable(wb, ...)`
JavaScript SDK	`wb.deleteDataTable(address: string)`
Python SDK	`wb.delete_data_table(address: str)`

Signature

async function deleteDataTable(wb: WorkbookContext, address: string): Promise<{
  touched: {
    [key: string]: string;
  };
  changed: string[];
  errors: {
    code: string;
    address: string;
    detail?: string;
    formula?: string;
  }[];
  invalidatedTiles: {
    sheet: string;
    tileRow: number;
    tileCol: number;
  }[];
  updatedSheets: {
    name: string;
    usedRange: | {
        startRow: number;
        startCol: number;
        endRow: number;
        endCol: number;
      }
    | null;
    tileRowCount: number;
    tileColCount: number;
  }[];
}>

listCharts

List charts in the workbook.

@param options - Options to filter by sheet @returns Array of chart summaries

Surface	Call
Exec	`await xlsx.listCharts(wb, ...)`
JavaScript SDK	`wb.listCharts(options: { sheet?: string } = {})`
Python SDK	`wb.list_charts(sheet: str \| None = None)`

Signature

async function listCharts(wb: WorkbookContext, options: { sheet?: string } = {}): Promise<{
  id?: number;
  sheet: string;
  name: string;
  type: string;
  groups: {
    type: string;
    axis?: 'primary' | 'secondary';
    seriesCount: number;
  }[];
  groupCount: number;
  seriesCount: number;
  position: {
    from: {
      cell: string;
      xOffsetPts?: number;
      yOffsetPts?: number;
    };
    to: {
      cell: string;
      xOffsetPts?: number;
      yOffsetPts?: number;
    };
    sheet: string;
  };
}[]>

getChart

Get a chart by name.

@param sheet - Sheet containing the chart @param name - Chart name @returns The chart info

Surface	Call
Exec	`await xlsx.getChart(wb, ...)`
JavaScript SDK	`wb.getChart(sheet: string, name: string)`
Python SDK	`wb.get_chart(sheet: str, name: str)`

Signature

async function getChart(wb: WorkbookContext, sheet: string, name: string): Promise<{
  id?: number;
  name: string;
  groups: {
    type: | 'column'
    | 'bar'
    | 'line'
    | 'area'
    | 'pie'
    | 'doughnut'
    | 'scatter'
    | 'bubble'
    | 'radar'
    | 'surface'
    | 'stockHLC'
    | 'stockOHLC'
    | 'waterfall'
    | 'histogram'
    | 'pareto'
    | 'funnel'
    | 'boxWhisker';
    scatterStyle?: 'line' | 'lineMarker' | 'marker' | 'smooth' | 'smoothMarker';
    radarStyle?: 'standard' | 'marker' | 'filled';
    surfaceVariant?: 'topView' | 'topViewWireframe';
    grouping?: 'standard' | 'stacked' | 'percentStacked';
    axis?: 'primary' | 'secondary';
    gapWidth?: number;
    overlap?: number;
    varyColors?: boolean;
    smooth?: boolean;
    bubbleScale?: number;
    showNegativeBubbles?: boolean;
    sizeRepresents?: 'area' | 'width';
    firstSliceAngle?: number;
    holeSize?: number;
    dataLabels?: {
      showLegendKey?: boolean;
      showValue?: boolean;
      showCategory?: boolean;
      showSeriesName?: boolean;
      showPercent?: boolean;
      showBubbleSize?: boolean;
      showLeaderLines?: boolean;
      position?: | 'bestFit' | 'center' | 'insideBase' | 'insideEnd' | 'outsideEnd' | 'left' | 'right' | 'top' | 'bottom';
      numberFormat?: string;
      numberFormatLinked?: boolean;
      separator?: string;
      format?: ChartDataLabelFormatSpec;
    };
    series: {
      name?: ChartTextSource;
      stockRole?: ChartStockRole;
      categories?: string;
      categoriesRefType?: 'string' | 'number' | 'multiLevelString';
      values?: string;
      xValues?: string;
      yValues?: string;
      bubbleSizes?: string;
      fillColor?: string;
      lineColor?: string;
      lineWidth?: number;
      lineDashStyle?: string;
      smooth?: boolean;
      invertIfNegative?: boolean;
      totalIndexes?: number[];
      showConnectorLines?: boolean;
      binOptions?: ChartBinOptionsSpec;
      quartileCalculation?: ChartBoxWhiskerQuartileCalculation;
      showInnerPoints?: boolean;
      showMeanLine?: boolean;
      showMeanMarker?: boolean;
      showOutlierPoints?: boolean;
      marker?: ChartMarkerSpec;
      dataLabels?: ChartDataLabelsSpec;
    }[];
  }[];
  title?: {
    text?: string;
    ref?: string;
    overlay?: boolean;
  };
  legend?: {
    visible?: boolean;
    position?: 'left' | 'right' | 'top' | 'bottom' | 'topRight';
    overlay?: boolean;
  };
  axes?: {
    category?: {
      title?: {
        text?: string;
        ref?: string;
      };
      visible?: boolean;
      categoryType?: 'category' | 'date';
      min?: number;
      max?: number;
      majorUnit?: number;
      minorUnit?: number;
      baseTimeUnit?: 'days' | 'months' | 'years';
      majorTimeUnit?: 'days' | 'months' | 'years';
      minorTimeUnit?: 'days' | 'months' | 'years';
      numberFormat?: string;
      numberFormatLinked?: boolean;
      reversed?: boolean;
      majorGridlines?: boolean;
      minorGridlines?: boolean;
      position?: 'left' | 'right' | 'top' | 'bottom';
    };
    value?: {
      title?: {
        text?: string;
        ref?: string;
      };
      visible?: boolean;
      categoryType?: 'category' | 'date';
      min?: number;
      max?: number;
      majorUnit?: number;
      minorUnit?: number;
      baseTimeUnit?: 'days' | 'months' | 'years';
      majorTimeUnit?: 'days' | 'months' | 'years';
      minorTimeUnit?: 'days' | 'months' | 'years';
      numberFormat?: string;
      numberFormatLinked?: boolean;
      reversed?: boolean;
      majorGridlines?: boolean;
      minorGridlines?: boolean;
      position?: 'left' | 'right' | 'top' | 'bottom';
    };
    secondaryCategory?: {
      title?: {
        text?: string;
        ref?: string;
      };
      visible?: boolean;
      categoryType?: 'category' | 'date';
      min?: number;
      max?: number;
      majorUnit?: number;
      minorUnit?: number;
      baseTimeUnit?: 'days' | 'months' | 'years';
      majorTimeUnit?: 'days' | 'months' | 'years';
      minorTimeUnit?: 'days' | 'months' | 'years';
      numberFormat?: string;
      numberFormatLinked?: boolean;
      reversed?: boolean;
      majorGridlines?: boolean;
      minorGridlines?: boolean;
      position?: 'left' | 'right' | 'top' | 'bottom';
    };
    secondaryValue?: {
      title?: {
        text?: string;
        ref?: string;
      };
      visible?: boolean;
      categoryType?: 'category' | 'date';
      min?: number;
      max?: number;
      majorUnit?: number;
      minorUnit?: number;
      baseTimeUnit?: 'days' | 'months' | 'years';
      majorTimeUnit?: 'days' | 'months' | 'years';
      minorTimeUnit?: 'days' | 'months' | 'years';
      numberFormat?: string;
      numberFormatLinked?: boolean;
      reversed?: boolean;
      majorGridlines?: boolean;
      minorGridlines?: boolean;
      position?: 'left' | 'right' | 'top' | 'bottom';
    };
  };
  format?: {
    fill?: {
      noFill?: boolean;
      color?: string;
    };
    border?: {
      noLine?: boolean;
      color?: string;
      weight?: number;
      lineStyle?: string;
    };
    font?: {
      bold?: boolean;
      color?: string;
      italic?: boolean;
      name?: string;
      size?: number;
      underline?: string;
    };
  };
  plotArea?: {
    format?: {
      fill?: {
        noFill?: boolean;
        color?: string;
      };
      border?: {
        noLine?: boolean;
        color?: string;
        weight?: number;
        lineStyle?: string;
      };
    };
  };
  displayBlanksAs?: 'gap' | 'span' | 'zero';
  plotVisibleOnly?: boolean;
  showDataLabelsOverMaximum?: boolean;
  roundedCorners?: boolean;
  styleId?: number;
  position: {
    from: {
      cell: string;
      xOffsetPts?: number;
      yOffsetPts?: number;
    };
    to: {
      cell: string;
      xOffsetPts?: number;
      yOffsetPts?: number;
    };
    sheet: string;
  };
}>

addChart

Add a chart to a sheet.

@param sheet - Sheet name @param chart - Chart specification @returns The created chart

Surface	Call
Exec	`await xlsx.addChart(wb, ...)`
JavaScript SDK	`wb.addChart(sheet: string, chart: ChartSpec)`
Python SDK	`wb.add_chart(sheet: str, chart: ChartSpec)`

Signature

async function addChart(wb: WorkbookContext, sheet: string, chart: ChartSpec): Promise<{
  id?: number;
  name: string;
  position: {
    from: {
      cell: string;
      xOffsetPts?: number;
      yOffsetPts?: number;
    };
    to: {
      cell: string;
      xOffsetPts?: number;
      yOffsetPts?: number;
    };
  };
  groups: {
    type: | 'column'
    | 'bar'
    | 'line'
    | 'area'
    | 'pie'
    | 'doughnut'
    | 'scatter'
    | 'bubble'
    | 'radar'
    | 'surface'
    | 'stockHLC'
    | 'stockOHLC'
    | 'waterfall'
    | 'histogram'
    | 'pareto'
    | 'funnel'
    | 'boxWhisker';
    scatterStyle?: 'line' | 'lineMarker' | 'marker' | 'smooth' | 'smoothMarker';
    radarStyle?: 'standard' | 'marker' | 'filled';
    surfaceVariant?: 'topView' | 'topViewWireframe';
    grouping?: 'standard' | 'stacked' | 'percentStacked';
    axis?: 'primary' | 'secondary';
    gapWidth?: number;
    overlap?: number;
    varyColors?: boolean;
    smooth?: boolean;
    bubbleScale?: number;
    showNegativeBubbles?: boolean;
    sizeRepresents?: 'area' | 'width';
    firstSliceAngle?: number;
    holeSize?: number;
    dataLabels?: {
      showLegendKey?: boolean;
      showValue?: boolean;
      showCategory?: boolean;
      showSeriesName?: boolean;
      showPercent?: boolean;
      showBubbleSize?: boolean;
      showLeaderLines?: boolean;
      position?: | 'bestFit' | 'center' | 'insideBase' | 'insideEnd' | 'outsideEnd' | 'left' | 'right' | 'top' | 'bottom';
      numberFormat?: string;
      numberFormatLinked?: boolean;
      separator?: string;
      format?: ChartDataLabelFormatSpec;
    };
    series: {
      name?: ChartTextSource;
      stockRole?: ChartStockRole;
      categories?: string;
      categoriesRefType?: 'string' | 'number' | 'multiLevelString';
      values?: string;
      xValues?: string;
      yValues?: string;
      bubbleSizes?: string;
      fillColor?: string;
      lineColor?: string;
      lineWidth?: number;
      lineDashStyle?: string;
      smooth?: boolean;
      invertIfNegative?: boolean;
      totalIndexes?: number[];
      showConnectorLines?: boolean;
      binOptions?: ChartBinOptionsSpec;
      quartileCalculation?: ChartBoxWhiskerQuartileCalculation;
      showInnerPoints?: boolean;
      showMeanLine?: boolean;
      showMeanMarker?: boolean;
      showOutlierPoints?: boolean;
      marker?: ChartMarkerSpec;
      dataLabels?: ChartDataLabelsSpec;
    }[];
  }[];
  title?: {
    text?: string;
    ref?: string;
    overlay?: boolean;
  };
  legend?: {
    visible?: boolean;
    position?: 'left' | 'right' | 'top' | 'bottom' | 'topRight';
    overlay?: boolean;
  };
  axes?: {
    category?: {
      title?: {
        text?: string;
        ref?: string;
      };
      visible?: boolean;
      categoryType?: 'category' | 'date';
      min?: number;
      max?: number;
      majorUnit?: number;
      minorUnit?: number;
      baseTimeUnit?: 'days' | 'months' | 'years';
      majorTimeUnit?: 'days' | 'months' | 'years';
      minorTimeUnit?: 'days' | 'months' | 'years';
      numberFormat?: string;
      numberFormatLinked?: boolean;
      reversed?: boolean;
      majorGridlines?: boolean;
      minorGridlines?: boolean;
      position?: 'left' | 'right' | 'top' | 'bottom';
    };
    value?: {
      title?: {
        text?: string;
        ref?: string;
      };
      visible?: boolean;
      categoryType?: 'category' | 'date';
      min?: number;
      max?: number;
      majorUnit?: number;
      minorUnit?: number;
      baseTimeUnit?: 'days' | 'months' | 'years';
      majorTimeUnit?: 'days' | 'months' | 'years';
      minorTimeUnit?: 'days' | 'months' | 'years';
      numberFormat?: string;
      numberFormatLinked?: boolean;
      reversed?: boolean;
      majorGridlines?: boolean;
      minorGridlines?: boolean;
      position?: 'left' | 'right' | 'top' | 'bottom';
    };
    secondaryCategory?: {
      title?: {
        text?: string;
        ref?: string;
      };
      visible?: boolean;
      categoryType?: 'category' | 'date';
      min?: number;
      max?: number;
      majorUnit?: number;
      minorUnit?: number;
      baseTimeUnit?: 'days' | 'months' | 'years';
      majorTimeUnit?: 'days' | 'months' | 'years';
      minorTimeUnit?: 'days' | 'months' | 'years';
      numberFormat?: string;
      numberFormatLinked?: boolean;
      reversed?: boolean;
      majorGridlines?: boolean;
      minorGridlines?: boolean;
      position?: 'left' | 'right' | 'top' | 'bottom';
    };
    secondaryValue?: {
      title?: {
        text?: string;
        ref?: string;
      };
      visible?: boolean;
      categoryType?: 'category' | 'date';
      min?: number;
      max?: number;
      majorUnit?: number;
      minorUnit?: number;
      baseTimeUnit?: 'days' | 'months' | 'years';
      majorTimeUnit?: 'days' | 'months' | 'years';
      minorTimeUnit?: 'days' | 'months' | 'years';
      numberFormat?: string;
      numberFormatLinked?: boolean;
      reversed?: boolean;
      majorGridlines?: boolean;
      minorGridlines?: boolean;
      position?: 'left' | 'right' | 'top' | 'bottom';
    };
  };
  format?: {
    fill?: {
      noFill?: boolean;
      color?: string;
    };
    border?: {
      noLine?: boolean;
      color?: string;
      weight?: number;
      lineStyle?: string;
    };
    font?: {
      bold?: boolean;
      color?: string;
      italic?: boolean;
      name?: string;
      size?: number;
      underline?: string;
    };
  };
  plotArea?: {
    format?: {
      fill?: {
        noFill?: boolean;
        color?: string;
      };
      border?: {
        noLine?: boolean;
        color?: string;
        weight?: number;
        lineStyle?: string;
      };
    };
  };
  displayBlanksAs?: 'gap' | 'span' | 'zero';
  plotVisibleOnly?: boolean;
  showDataLabelsOverMaximum?: boolean;
  roundedCorners?: boolean;
  styleId?: number;
}>

setChart

Update a chart.

@param sheet - Sheet containing the chart @param name - Chart name @param chart - Updated chart specification @returns The updated chart

Surface	Call
Exec	`await xlsx.setChart(wb, ...)`
JavaScript SDK	`wb.setChart(sheet: string, name: string, chart: ChartSpec)`
Python SDK	`wb.set_chart(sheet: str, name: str, chart: ChartSpec)`

Signature

async function setChart(wb: WorkbookContext, sheet: string, name: string, chart: ChartSpec): Promise<{
  id?: number;
  name: string;
  position: {
    from: {
      cell: string;
      xOffsetPts?: number;
      yOffsetPts?: number;
    };
    to: {
      cell: string;
      xOffsetPts?: number;
      yOffsetPts?: number;
    };
  };
  groups: {
    type: | 'column'
    | 'bar'
    | 'line'
    | 'area'
    | 'pie'
    | 'doughnut'
    | 'scatter'
    | 'bubble'
    | 'radar'
    | 'surface'
    | 'stockHLC'
    | 'stockOHLC'
    | 'waterfall'
    | 'histogram'
    | 'pareto'
    | 'funnel'
    | 'boxWhisker';
    scatterStyle?: 'line' | 'lineMarker' | 'marker' | 'smooth' | 'smoothMarker';
    radarStyle?: 'standard' | 'marker' | 'filled';
    surfaceVariant?: 'topView' | 'topViewWireframe';
    grouping?: 'standard' | 'stacked' | 'percentStacked';
    axis?: 'primary' | 'secondary';
    gapWidth?: number;
    overlap?: number;
    varyColors?: boolean;
    smooth?: boolean;
    bubbleScale?: number;
    showNegativeBubbles?: boolean;
    sizeRepresents?: 'area' | 'width';
    firstSliceAngle?: number;
    holeSize?: number;
    dataLabels?: {
      showLegendKey?: boolean;
      showValue?: boolean;
      showCategory?: boolean;
      showSeriesName?: boolean;
      showPercent?: boolean;
      showBubbleSize?: boolean;
      showLeaderLines?: boolean;
      position?: | 'bestFit' | 'center' | 'insideBase' | 'insideEnd' | 'outsideEnd' | 'left' | 'right' | 'top' | 'bottom';
      numberFormat?: string;
      numberFormatLinked?: boolean;
      separator?: string;
      format?: ChartDataLabelFormatSpec;
    };
    series: {
      name?: ChartTextSource;
      stockRole?: ChartStockRole;
      categories?: string;
      categoriesRefType?: 'string' | 'number' | 'multiLevelString';
      values?: string;
      xValues?: string;
      yValues?: string;
      bubbleSizes?: string;
      fillColor?: string;
      lineColor?: string;
      lineWidth?: number;
      lineDashStyle?: string;
      smooth?: boolean;
      invertIfNegative?: boolean;
      totalIndexes?: number[];
      showConnectorLines?: boolean;
      binOptions?: ChartBinOptionsSpec;
      quartileCalculation?: ChartBoxWhiskerQuartileCalculation;
      showInnerPoints?: boolean;
      showMeanLine?: boolean;
      showMeanMarker?: boolean;
      showOutlierPoints?: boolean;
      marker?: ChartMarkerSpec;
      dataLabels?: ChartDataLabelsSpec;
    }[];
  }[];
  title?: {
    text?: string;
    ref?: string;
    overlay?: boolean;
  };
  legend?: {
    visible?: boolean;
    position?: 'left' | 'right' | 'top' | 'bottom' | 'topRight';
    overlay?: boolean;
  };
  axes?: {
    category?: {
      title?: {
        text?: string;
        ref?: string;
      };
      visible?: boolean;
      categoryType?: 'category' | 'date';
      min?: number;
      max?: number;
      majorUnit?: number;
      minorUnit?: number;
      baseTimeUnit?: 'days' | 'months' | 'years';
      majorTimeUnit?: 'days' | 'months' | 'years';
      minorTimeUnit?: 'days' | 'months' | 'years';
      numberFormat?: string;
      numberFormatLinked?: boolean;
      reversed?: boolean;
      majorGridlines?: boolean;
      minorGridlines?: boolean;
      position?: 'left' | 'right' | 'top' | 'bottom';
    };
    value?: {
      title?: {
        text?: string;
        ref?: string;
      };
      visible?: boolean;
      categoryType?: 'category' | 'date';
      min?: number;
      max?: number;
      majorUnit?: number;
      minorUnit?: number;
      baseTimeUnit?: 'days' | 'months' | 'years';
      majorTimeUnit?: 'days' | 'months' | 'years';
      minorTimeUnit?: 'days' | 'months' | 'years';
      numberFormat?: string;
      numberFormatLinked?: boolean;
      reversed?: boolean;
      majorGridlines?: boolean;
      minorGridlines?: boolean;
      position?: 'left' | 'right' | 'top' | 'bottom';
    };
    secondaryCategory?: {
      title?: {
        text?: string;
        ref?: string;
      };
      visible?: boolean;
      categoryType?: 'category' | 'date';
      min?: number;
      max?: number;
      majorUnit?: number;
      minorUnit?: number;
      baseTimeUnit?: 'days' | 'months' | 'years';
      majorTimeUnit?: 'days' | 'months' | 'years';
      minorTimeUnit?: 'days' | 'months' | 'years';
      numberFormat?: string;
      numberFormatLinked?: boolean;
      reversed?: boolean;
      majorGridlines?: boolean;
      minorGridlines?: boolean;
      position?: 'left' | 'right' | 'top' | 'bottom';
    };
    secondaryValue?: {
      title?: {
        text?: string;
        ref?: string;
      };
      visible?: boolean;
      categoryType?: 'category' | 'date';
      min?: number;
      max?: number;
      majorUnit?: number;
      minorUnit?: number;
      baseTimeUnit?: 'days' | 'months' | 'years';
      majorTimeUnit?: 'days' | 'months' | 'years';
      minorTimeUnit?: 'days' | 'months' | 'years';
      numberFormat?: string;
      numberFormatLinked?: boolean;
      reversed?: boolean;
      majorGridlines?: boolean;
      minorGridlines?: boolean;
      position?: 'left' | 'right' | 'top' | 'bottom';
    };
  };
  format?: {
    fill?: {
      noFill?: boolean;
      color?: string;
    };
    border?: {
      noLine?: boolean;
      color?: string;
      weight?: number;
      lineStyle?: string;
    };
    font?: {
      bold?: boolean;
      color?: string;
      italic?: boolean;
      name?: string;
      size?: number;
      underline?: string;
    };
  };
  plotArea?: {
    format?: {
      fill?: {
        noFill?: boolean;
        color?: string;
      };
      border?: {
        noLine?: boolean;
        color?: string;
        weight?: number;
        lineStyle?: string;
      };
    };
  };
  displayBlanksAs?: 'gap' | 'span' | 'zero';
  plotVisibleOnly?: boolean;
  showDataLabelsOverMaximum?: boolean;
  roundedCorners?: boolean;
  styleId?: number;
}>

deleteChart

Delete a chart.

@param sheet - Sheet containing the chart @param name - Chart name

Surface	Call
Exec	`await xlsx.deleteChart(wb, ...)`
JavaScript SDK	`wb.deleteChart(sheet: string, name: string)`
Python SDK	`wb.delete_chart(sheet: str, name: str)`

Signature

async function deleteChart(wb: WorkbookContext, sheet: string, name: string): Promise<void>

Images and drawings

listImages

List worksheet images in the workbook.

@param options - Options to filter by sheet @returns Array of image metadata

Surface	Call
Exec	`await xlsx.listImages(wb, ...)`
JavaScript SDK	`wb.listImages(options: { sheet?: string } = {})`
Python SDK	`wb.list_images(sheet: str \| None = None)`

Signature

async function listImages(wb: WorkbookContext, options: { sheet?: string } = {}): Promise<{
  id?: number;
  sheet: string;
  name: string;
  position: {
    from: {
      cell: string;
      xOffsetPts?: number;
      yOffsetPts?: number;
    };
    to: {
      cell: string;
      xOffsetPts?: number;
      yOffsetPts?: number;
    };
    sheet?: string;
  };
  format?: 'png' | 'jpeg';
  widthPts?: number;
  heightPts?: number;
  naturalWidthPx?: number;
  naturalHeightPx?: number;
  altText?: string | null;
  altTextTitle?: string | null;
}[]>

getImage

Get worksheet image metadata by name or id.

@param sheet - Sheet containing the image @param selector - Image name or sheet-local id @returns The image metadata

Surface	Call
Exec	`await xlsx.getImage(wb, ...)`
JavaScript SDK	`wb.getImage(sheet: string, selector: ImageSelector)`
Python SDK	`wb.get_image(sheet: str, name: str \| None = None, id: int \| None = None)`

Signature

async function getImage(wb: WorkbookContext, sheet: string, selector: ImageSelector): Promise<{
  id?: number;
  sheet: string;
  name: string;
  position: {
    from: {
      cell: string;
      xOffsetPts?: number;
      yOffsetPts?: number;
    };
    to: {
      cell: string;
      xOffsetPts?: number;
      yOffsetPts?: number;
    };
    sheet?: string;
  };
  format?: 'png' | 'jpeg';
  widthPts?: number;
  heightPts?: number;
  naturalWidthPx?: number;
  naturalHeightPx?: number;
  altText?: string | null;
  altTextTitle?: string | null;
}>

addImage

Add a PNG or JPEG image to a sheet.

@param sheet - Sheet name @param image - Image specification @returns The created image metadata

For CLI scripts, pass local image files with --input-file logo=@./logo.png; the script receives input.logo as a data:image/...;base64,... URI suitable for image.source.base64.

Surface	Call
Exec	`await xlsx.addImage(wb, ...)`
JavaScript SDK	`wb.addImage(sheet: string, image: ImageSpec)`
Python SDK	`wb.add_image(sheet: str, image: ImageSpec)`

Signature

async function addImage(wb: WorkbookContext, sheet: string, image: ImageSpec): Promise<{
  id?: number;
  sheet: string;
  name: string;
  position: {
    from: {
      cell: string;
      xOffsetPts?: number;
      yOffsetPts?: number;
    };
    to: {
      cell: string;
      xOffsetPts?: number;
      yOffsetPts?: number;
    };
    sheet?: string;
  };
  format?: 'png' | 'jpeg';
  widthPts?: number;
  heightPts?: number;
  naturalWidthPx?: number;
  naturalHeightPx?: number;
  altText?: string | null;
  altTextTitle?: string | null;
}>

setImage

Update worksheet image metadata, placement, or source bytes.

@param sheet - Sheet containing the image @param selector - Image name or sheet-local id @param image - Image updates @returns The updated image metadata

Surface	Call
Exec	`await xlsx.setImage(wb, ...)`
JavaScript SDK	`wb.setImage(sheet: string, selector: ImageSelector, image: ImageUpdate)`
Python SDK	`wb.set_image(sheet: str, image: ImageUpdate, name: str \| None = None, id: int \| None = None)`

Signature

async function setImage(wb: WorkbookContext, sheet: string, selector: ImageSelector, image: ImageUpdate): Promise<{
  id?: number;
  sheet: string;
  name: string;
  position: {
    from: {
      cell: string;
      xOffsetPts?: number;
      yOffsetPts?: number;
    };
    to: {
      cell: string;
      xOffsetPts?: number;
      yOffsetPts?: number;
    };
    sheet?: string;
  };
  format?: 'png' | 'jpeg';
  widthPts?: number;
  heightPts?: number;
  naturalWidthPx?: number;
  naturalHeightPx?: number;
  altText?: string | null;
  altTextTitle?: string | null;
}>

deleteImage

Delete a worksheet image by name or id.

@param sheet - Sheet containing the image @param selector - Image name or sheet-local id

Surface	Call
Exec	`await xlsx.deleteImage(wb, ...)`
JavaScript SDK	`wb.deleteImage(sheet: string, selector: ImageSelector)`
Python SDK	`wb.delete_image(sheet: str, name: str \| None = None, id: int \| None = None)`

Signature

async function deleteImage(wb: WorkbookContext, sheet: string, selector: ImageSelector): Promise<void>

Writing and structure

setCells

Set values in multiple cells.

@param cells - Array of cell assignments @returns Write result with changed cells and any errors

Surface	Call
Exec	`await xlsx.setCells(wb, ...)`
JavaScript SDK	`wb.setCells(cells: CellAssignment[], options: { validationMode?: SetCellsValidationMode } = {})`
Python SDK	`wb.set_cells(cells: Sequence[JsonMapping], validation_mode: SetCellsValidationMode \| None = None)`

Signature

async function setCells(wb: WorkbookContext, cells: CellAssignment[], options: { validationMode?: SetCellsValidationMode } = {}): Promise<{
  touched: {
    [key: string]: string;
  };
  changed: string[];
  errors: {
    code: string;
    address: string;
    detail?: string;
    formula?: string;
  }[];
  invalidatedTiles: {
    sheet: string;
    tileRow: number;
    tileCol: number;
  }[];
  updatedSheets: {
    name: string;
    usedRange: | {
        startRow: number;
        startCol: number;
        endRow: number;
        endCol: number;
      }
    | null;
    tileRowCount: number;
    tileColCount: number;
  }[];
}>

copyRange

Copy a range to another location.

@param source - Source range address @param destination - Destination cell address @param options - Copy options @returns Copy result with destination and cell count

Surface	Call
Exec	`await xlsx.copyRange(wb, ...)`
JavaScript SDK	`wb.copyRange(source: string, destination: string, options: { pasteType?: PasteType } = {})`
Python SDK	`wb.copy_range(source: RangeRef, destination: CellRef, paste_type: Literal["all", "values", "formulas", "formats"] \| None = None)`

Signature

async function copyRange(wb: WorkbookContext, source: string, destination: string, options: { pasteType?: PasteType } = {}): Promise<{
  destination: string;
  cellsCopied: number;
}>

scaleRange

Scale numeric values in a range by a factor. This is a composite operation that reads the range, filters numeric cells, and calls setCells with the scaled values.

@param range - Range address @param factor - Multiplication factor @param options - Scale options @returns Write result, or null if no numeric cells were found

Surface	Call
Exec	`await xlsx.scaleRange(wb, ...)`
JavaScript SDK	`wb.scaleRange(range: string, factor: number, options: { skipFormulas?: boolean } = {})`
Python SDK	`wb.scale_range(range: RangeRef, factor: float, skip_formulas: bool = True)`

Signature

async function scaleRange(wb: WorkbookContext, range: string, factor: number, options: { skipFormulas?: boolean } = {}): Promise<| {
    touched: {
      [key: string]: string;
    };
    changed: string[];
    errors: {
      code: string;
      address: string;
      detail?: string;
      formula?: string;
    }[];
    invalidatedTiles: {
      sheet: string;
      tileRow: number;
      tileCol: number;
    }[];
    updatedSheets: {
      name: string;
      usedRange: | {
          startRow: number;
          startCol: number;
          endRow: number;
          endCol: number;
        }
      | null;
      tileRowCount: number;
      tileColCount: number;
    }[];
  }
| null>

insertRowAfter

Insert rows after a specified row.

@param sheet - Sheet name @param row - Row number after which to insert (1-based) @param count - Number of rows to insert (default: 1)

Surface	Call
Exec	`await xlsx.insertRowAfter(wb, ...)`
JavaScript SDK	`wb.insertRowAfter(sheet: string, row: number, count: number = 1)`
Python SDK	`wb.insert_row_after(sheet_name: str, row: int, count: int = 1)`

Signature

async function insertRowAfter(wb: WorkbookContext, sheet: string, row: number, count: number = 1): Promise<void>

deleteRows

Delete rows from a sheet.

@param sheet - Sheet name @param row - Starting row number (1-based) @param count - Number of rows to delete (default: 1)

Surface	Call
Exec	`await xlsx.deleteRows(wb, ...)`
JavaScript SDK	`wb.deleteRows(sheet: string, row: number, count: number = 1)`
Python SDK	`wb.delete_rows(sheet_name: str, row: int, count: int = 1)`

Signature

async function deleteRows(wb: WorkbookContext, sheet: string, row: number, count: number = 1): Promise<void>

insertColumnAfter

Insert columns after a specified column.

@param sheet - Sheet name @param column - Column number (1-based) or letter after which to insert @param count - Number of columns to insert (default: 1)

Surface	Call
Exec	`await xlsx.insertColumnAfter(wb, ...)`
JavaScript SDK	`wb.insertColumnAfter(sheet: string, column: number \| string, count: number = 1)`
Python SDK	`wb.insert_column_after(sheet_name: str, column: int \| str, count: int = 1)`

Signature

async function insertColumnAfter(wb: WorkbookContext, sheet: string, column: number | string, count: number = 1): Promise<void>

deleteColumns

Delete columns from a sheet.

@param sheet - Sheet name @param column - Starting column number (1-based) or letter @param count - Number of columns to delete (default: 1)

Surface	Call
Exec	`await xlsx.deleteColumns(wb, ...)`
JavaScript SDK	`wb.deleteColumns(sheet: string, column: number \| string, count: number = 1)`
Python SDK	`wb.delete_columns(sheet_name: str, column: int \| str, count: int = 1)`

Signature

async function deleteColumns(wb: WorkbookContext, sheet: string, column: number | string, count: number = 1): Promise<void>

setRowProperties

Set properties for a range of rows.

@param sheet - Sheet name @param fromRow - Starting row number (1-based) @param toRow - Ending row number (1-based) @param properties - Properties to set (e.g., height, hidden)

Surface	Call
Exec	`await xlsx.setRowProperties(wb, ...)`
JavaScript SDK	`wb.setRowProperties(sheet: string, fromRow: number, toRow: number, properties: RowProperties)`
Python SDK	`wb.set_row_properties(sheet_name: str, from_row: int, to_row: int, properties: RowProperties)`

Signature

async function setRowProperties(wb: WorkbookContext, sheet: string, fromRow: number, toRow: number, properties: RowProperties): Promise<void>

setColumnProperties

Set properties for a range of columns.

@param sheet - Sheet name @param fromCol - Starting column number (1-based) or letter @param toCol - Ending column number (1-based) or letter @param properties - Properties to set (e.g., width, hidden)

Surface	Call
Exec	`await xlsx.setColumnProperties(wb, ...)`
JavaScript SDK	`wb.setColumnProperties(sheet: string, fromCol: number \| string, toCol: number \| string, properties: ColumnProperties)`
Python SDK	`wb.set_column_properties(sheet_name: str, from_col: int \| str, to_col: int \| str, properties: ColumnProperties)`

Signature

async function setColumnProperties(wb: WorkbookContext, sheet: string, fromCol: number | string, toCol: number | string, properties: ColumnProperties): Promise<void>

autoFitColumns

Auto-fit column widths to content.

@param sheet - Sheet name @param columns - Specific columns to fit (default: all) @param options - Auto-fit options @returns Map of column letters to width results

Surface	Call
Exec	`await xlsx.autoFitColumns(wb, ...)`
JavaScript SDK	`wb.autoFitColumns(sheet: string, columns?: (number \| string)[], options: { minWidth?: number; maxWidth?: number; padding?: number } = {})`
Python SDK	`wb.auto_fit_columns(sheet_name: str, columns: Sequence[int \| str] \| None = None, min_width: float \| None = None, max_width: float \| None = None, padding: float \| None = None)`

Signature

async function autoFitColumns(wb: WorkbookContext, sheet: string, columns?: (number | string)[], options: { minWidth?: number; maxWidth?: number; padding?: number } = {}): Promise<{
  [key: string]: {
  width: number;
  previousWidth: number;
};
}>

autoFitRows

Auto-fit row heights to content.

@param sheet - Sheet name @param rows - Specific rows to fit (default: all) @param options - Auto-fit options @returns Map of row numbers to height results

Surface	Call
Exec	`await xlsx.autoFitRows(wb, ...)`
JavaScript SDK	`wb.autoFitRows(sheet: string, rows?: number[], options: { minHeight?: number; maxHeight?: number } = {})`
Python SDK	`wb.auto_fit_rows(sheet_name: str, rows: Sequence[int] \| None = None, min_height: float \| None = None, max_height: float \| None = None)`

Signature

async function autoFitRows(wb: WorkbookContext, sheet: string, rows?: number[], options: { minHeight?: number; maxHeight?: number } = {}): Promise<{
  [key: string]: {
  height: number;
  previousHeight: number;
  hidden: boolean;
  previousHidden: boolean;
};
}>

sortRange

Sort a range by specified columns.

@param range - Range address to sort @param keys - Sort keys specifying columns and order @param options - Sort options

Surface	Call
Exec	`await xlsx.sortRange(wb, ...)`
JavaScript SDK	`wb.sortRange(range: string, keys: SortKey[], options: { hasHeader?: boolean } = {})`
Python SDK	`wb.sort_range(range: RangeRef, keys: Sequence[JsonMapping], has_header: bool \| None = None)`

Signature

async function sortRange(wb: WorkbookContext, range: string, keys: SortKey[], options: { hasHeader?: boolean } = {}): Promise<void>

Styles and formatting

setStyle

Set the style of a cell or range.

@param target - Cell or range address @param style - Style properties to apply

Surface	Call
Exec	`await xlsx.setStyle(wb, ...)`
JavaScript SDK	`wb.setStyle(target: string, style: Style)`
Python SDK	`wb.set_style(target: CellRef \| RangeRef, style: Style)`

Signature

async function setStyle(wb: WorkbookContext, target: string, style: Style): Promise<void>

getConditionalFormatting

Get conditional formatting rules for a sheet.

@param sheet - Sheet name @returns Array of conditional formatting rules

Surface	Call
Exec	`await xlsx.getConditionalFormatting(wb, ...)`
JavaScript SDK	`wb.getConditionalFormatting(sheet: string)`
Python SDK	`wb.get_conditional_formatting(sheet_name: str)`

Signature

async function getConditionalFormatting(wb: WorkbookContext, sheet: string): Promise<{
  address: string;
  type: | 'cellValue'
  | 'containsText'
  | 'notContainsText'
  | 'beginsWith'
  | 'endsWith'
  | 'containsBlanks'
  | 'notContainsBlanks'
  | 'containsErrors'
  | 'notContainsErrors'
  | 'expression'
  | 'timePeriod'
  | 'top'
  | 'bottom'
  | 'aboveAverage'
  | 'belowAverage'
  | 'duplicateValues'
  | 'uniqueValues'
  | 'twoColorScale'
  | 'threeColorScale'
  | 'dataBar'
  | 'iconSet';
  index?: number;
  priority?: number;
  stopIfTrue?: boolean;
  style?: {
    fill?: | {
        color?: string;
        pattern?: string;
        patternColor?: string;
        gradient?: GradientFill;
      }
    | null;
    font?: | {
        name?: string;
        size?: number;
        color?: string;
        bold?: boolean;
        italic?: boolean;
        strike?: boolean;
        underline?: string;
        verticalAlign?: string;
      }
    | null;
    alignment?: | {
        horizontal?: string;
        vertical?: string;
        rotation?: number;
        wrapText?: boolean;
        shrinkToFit?: boolean;
        indent?: number;
        readingOrder?: 'context' | 'leftToRight' | 'rightToLeft';
        autoIndent?: boolean;
      }
    | null;
    protection?: | {
        locked?: boolean;
        formulaHidden?: boolean;
      }
    | null;
    border?: | {
        top?: BorderEdgeStyle;
        bottom?: BorderEdgeStyle;
        left?: BorderEdgeStyle;
        right?: BorderEdgeStyle;
        diagonal?: DiagonalBorderStyle;
      }
    | null;
    numberFormat?: string | null;
    centerContinuousSpan?: number | null;
    richText?: RichTextRun[] | null;
  };
  operator?: | 'equal'
  | 'notEqual'
  | 'greaterThan'
  | 'greaterThanOrEqual'
  | 'lessThan'
  | 'lessThanOrEqual'
  | 'between'
  | 'notBetween';
  formula?: string;
  formula2?: string;
  text?: string;
  rank?: number;
  percent?: boolean;
  equalAverage?: boolean;
  stdDev?: number;
  lowValue?: {
    type: 'formula' | 'max' | 'min' | 'num' | 'percent' | 'percentile' | 'autoMin' | 'autoMax';
    value?: number;
    formula?: string;
    color?: string;
  };
  midValue?: {
    type: 'formula' | 'max' | 'min' | 'num' | 'percent' | 'percentile' | 'autoMin' | 'autoMax';
    value?: number;
    formula?: string;
    color?: string;
  };
  highValue?: {
    type: 'formula' | 'max' | 'min' | 'num' | 'percent' | 'percentile' | 'autoMin' | 'autoMax';
    value?: number;
    formula?: string;
    color?: string;
  };
  dataBar?: {
    showValue?: boolean;
    gradient?: boolean;
    border?: boolean;
    negativeBarColorSameAsPositive?: boolean;
    negativeBarBorderColorSameAsPositive?: boolean;
    axisPosition?: 'automatic' | 'middle' | 'none';
    direction?: 'context' | 'leftToRight' | 'rightToLeft';
    fillColor?: string;
    borderColor?: string;
    negativeFillColor?: string;
    negativeBorderColor?: string;
    axisColor?: string;
    lowValue?: {
      type: | 'formula' | 'max' | 'min' | 'num' | 'percent' | 'percentile' | 'autoMin' | 'autoMax';
      value?: number;
      formula?: string;
    };
    highValue?: {
      type: | 'formula' | 'max' | 'min' | 'num' | 'percent' | 'percentile' | 'autoMin' | 'autoMax';
      value?: number;
      formula?: string;
    };
  };
  iconSetStyle?: string;
  timePeriod?: | 'today'
  | 'yesterday'
  | 'tomorrow'
  | 'last7Days'
  | 'thisWeek'
  | 'lastWeek'
  | 'nextWeek'
  | 'thisMonth'
  | 'lastMonth'
  | 'nextMonth';
}[]>

setConditionalFormatting

Set conditional formatting rules for a sheet.

@param sheet - Sheet name @param rules - Array of conditional formatting rules @param options - Options including whether to clear existing rules

Surface	Call
Exec	`await xlsx.setConditionalFormatting(wb, ...)`
JavaScript SDK	`wb.setConditionalFormatting(sheet: string, rules: ConditionalFormattingRule[], options: { clear?: boolean } = {})`
Python SDK	`wb.set_conditional_formatting(sheet_name: str, rules: Sequence[ConditionalFormattingRule], clear: bool \| None = None)`

Signature

async function setConditionalFormatting(wb: WorkbookContext, sheet: string, rules: ConditionalFormattingRule[], options: { clear?: boolean } = {}): Promise<void>

removeConditionalFormatting

Remove conditional formatting rules by index.

@param sheet - Sheet name @param indices - Indices of rules to remove

Surface	Call
Exec	`await xlsx.removeConditionalFormatting(wb, ...)`
JavaScript SDK	`wb.removeConditionalFormatting(sheet: string, indices: number[])`
Python SDK	`wb.remove_conditional_formatting(sheet_name: str, indices: Sequence[int])`

Signature

async function removeConditionalFormatting(wb: WorkbookContext, sheet: string, indices: number[]): Promise<void>

getStyle

Get the style of a cell.

@param cell - Cell address @returns Style properties

Surface	Call
Exec	`await xlsx.getStyle(wb, ...)`
JavaScript SDK	`wb.getStyle(cell: string)`
Python SDK	`wb.get_style(cell: CellRef)`

Signature

async function getStyle(wb: WorkbookContext, cell: string): Promise<{
  fill?: | {
      color?: string;
      pattern?: string;
      patternColor?: string;
      gradient?: {
        type: string;
        degree?: number;
        color1: string;
        color2: string;
        top?: number;
        bottom?: number;
        left?: number;
        right?: number;
      };
    }
  | null;
  font?: | {
      name?: string;
      size?: number;
      color?: string;
      bold?: boolean;
      italic?: boolean;
      strike?: boolean;
      underline?: string;
      verticalAlign?: string;
    }
  | null;
  alignment?: | {
      horizontal?: string;
      vertical?: string;
      rotation?: number;
      wrapText?: boolean;
      shrinkToFit?: boolean;
      indent?: number;
      readingOrder?: 'context' | 'leftToRight' | 'rightToLeft';
      autoIndent?: boolean;
    }
  | null;
  protection?: | {
      locked?: boolean;
      formulaHidden?: boolean;
    }
  | null;
  border?: | {
      top?: {
        style?: string;
        color?: string;
        themeColor?: | 'background1' | 'light1' | 'text1' | 'dark1' | 'background2' | 'light2' | 'text2' | 'dark2' | 'accent1' | 'accent2' | 'accent3' | 'accent4' | 'accent5' | 'accent6' | 'hyperlink' | 'followedHyperlink';
        tintAndShade?: number;
      };
      bottom?: {
        style?: string;
        color?: string;
        themeColor?: | 'background1' | 'light1' | 'text1' | 'dark1' | 'background2' | 'light2' | 'text2' | 'dark2' | 'accent1' | 'accent2' | 'accent3' | 'accent4' | 'accent5' | 'accent6' | 'hyperlink' | 'followedHyperlink';
        tintAndShade?: number;
      };
      left?: {
        style?: string;
        color?: string;
        themeColor?: | 'background1' | 'light1' | 'text1' | 'dark1' | 'background2' | 'light2' | 'text2' | 'dark2' | 'accent1' | 'accent2' | 'accent3' | 'accent4' | 'accent5' | 'accent6' | 'hyperlink' | 'followedHyperlink';
        tintAndShade?: number;
      };
      right?: {
        style?: string;
        color?: string;
        themeColor?: | 'background1' | 'light1' | 'text1' | 'dark1' | 'background2' | 'light2' | 'text2' | 'dark2' | 'accent1' | 'accent2' | 'accent3' | 'accent4' | 'accent5' | 'accent6' | 'hyperlink' | 'followedHyperlink';
        tintAndShade?: number;
      };
      diagonal?: {
        style?: string;
        color?: string;
        themeColor?: | 'background1' | 'light1' | 'text1' | 'dark1' | 'background2' | 'light2' | 'text2' | 'dark2' | 'accent1' | 'accent2' | 'accent3' | 'accent4' | 'accent5' | 'accent6' | 'hyperlink' | 'followedHyperlink';
        tintAndShade?: number;
        up?: boolean;
        down?: boolean;
      };
    }
  | null;
  numberFormat?: string | null;
  centerContinuousSpan?: number | null;
  richText?: | {
      text: string;
      style?: {
        name?: string;
        size?: number;
        color?: string;
        bold?: boolean;
        italic?: boolean;
        strike?: boolean;
        underline?: string;
        verticalAlign?: string;
      };
    }[]
  | null;
}>

Data validation

getDataValidations

Get data validation rules.

@param options - Optional sheet and address filters @returns Array of data validation rules

Surface	Call
Exec	`await xlsx.getDataValidations(wb, ...)`
JavaScript SDK	`wb.getDataValidations(options: { sheet?: string; address?: string } = {})`
Python SDK	`wb.get_data_validations(sheet: str \| None = None, address: str \| None = None)`

Signature

async function getDataValidations(wb: WorkbookContext, options: { sheet?: string; address?: string } = {}): Promise<{
  address: string;
  rule: {
    wholeNumber?: | {
        operator: DataValidationOperator;
        formula1: string | number;
        formula2?: string | number | null;
      }
    | null;
    decimal?: | {
        operator: DataValidationOperator;
        formula1: string | number;
        formula2?: string | number | null;
      }
    | null;
    list?: | {
        source: string;
        inCellDropDown?: boolean;
      }
    | null;
    date?: | {
        operator: DataValidationOperator;
        formula1: string | number;
        formula2?: string | number | null;
      }
    | null;
    time?: | {
        operator: DataValidationOperator;
        formula1: string | number;
        formula2?: string | number | null;
      }
    | null;
    textLength?: | {
        operator: DataValidationOperator;
        formula1: string | number;
        formula2?: string | number | null;
      }
    | null;
    custom?: | {
        formula: string;
      }
    | null;
  };
  index: number;
  sheet: string;
  type: 'None' | 'WholeNumber' | 'Decimal' | 'List' | 'Date' | 'Time' | 'TextLength' | 'Custom';
  ignoreBlanks: boolean;
  prompt: Required<DataValidationPrompt>;
  errorAlert: Required<DataValidationErrorAlert>;
}[]>

setDataValidations

Add data validation rules to a sheet.

@param sheet - Sheet name @param rules - Rules to add @param options - Options including whether to clear existing rules

Surface	Call
Exec	`await xlsx.setDataValidations(wb, ...)`
JavaScript SDK	`wb.setDataValidations(sheet: string, rules: DataValidationSpec[], options: { clear?: boolean } = {})`
Python SDK	`wb.set_data_validations(sheet_name: str, rules: Sequence[DataValidationSpec], clear: bool \| None = None)`

Signature

async function setDataValidations(wb: WorkbookContext, sheet: string, rules: DataValidationSpec[], options: { clear?: boolean } = {}): Promise<void>

removeDataValidations

Remove data validation rules by index or by range.

@param sheet - Sheet name @param target - Either rule indices or an address to clear

Surface	Call
Exec	`await xlsx.removeDataValidations(wb, ...)`
JavaScript SDK	`wb.removeDataValidations(sheet: string, target: { indices: number[] } \| { address: string })`
Python SDK	`wb.remove_data_validations(sheet_name: str, indices: Sequence[int] \| None = None, address: str \| None = None)`

Signature

async function removeDataValidations(wb: WorkbookContext, sheet: string, target: { indices: number[] } | { address: string }): Promise<void>

Formulas and dependencies

evaluateFormulas

Evaluate multiple formulas in a sheet context.

@param sheet - Sheet name for formula context @param formulas - Array of formula strings @returns Array of formula results

Surface	Call
Exec	`await xlsx.evaluateFormulas(wb, ...)`
JavaScript SDK	`wb.evaluateFormulas(sheet: string, formulas: string[])`
Python SDK	`wb.evaluate_formulas(sheet: str, formulas: Sequence[str])`

Signature

async function evaluateFormulas(wb: WorkbookContext, sheet: string, formulas: string[]): Promise<{
  formula: string;
  value: unknown;
  error?: {
    [key: string]: unknown;
  };
}[]>

evaluateFormula

Evaluate a single formula in a sheet context. This is a convenience wrapper around evaluateFormulas.

@param sheet - Sheet name for formula context @param formula - Formula string @returns The formula result

Surface	Call
Exec	`await xlsx.evaluateFormula(wb, ...)`
JavaScript SDK	`wb.evaluateFormula(sheet: string, formula: string)`
Python SDK	`wb.evaluate_formula(sheet: str, formula: str)`

Signature

async function evaluateFormula(wb: WorkbookContext, sheet: string, formula: string): Promise<{
  formula: string;
  value: unknown;
  error?: {
    [key: string]: unknown;
  };
}>

getCellPrecedents

Get cells that a formula depends on (precedents).

@param address - Cell address @param depth - How many levels to trace (default: 1, use Infinity for all) @returns Dependency result with cells and warnings

Surface	Call
Exec	`await xlsx.getCellPrecedents(wb, ...)`
JavaScript SDK	`wb.getCellPrecedents(address: string, depth: number \| typeof Infinity = 1)`
Python SDK	`wb.get_cell_precedents(address: CellRef, depth: int \| float = 1)`

Signature

async function getCellPrecedents(wb: WorkbookContext, address: string, depth: number | typeof Infinity = 1): Promise<{
  cells: {
    address: string;
    depth: number;
    formula?: string;
    referenceType?: 'direct' | 'range' | 'named' | 'table';
  }[];
  warnings?: {
    code: string;
    address: string;
    detail?: string;
    formula?: string;
  }[];
}>

getCellDependents

Get cells that depend on a cell (dependents).

@param address - Cell address @param depth - How many levels to trace (default: 1, use Infinity for all) @returns Dependency result with cells and warnings

Surface	Call
Exec	`await xlsx.getCellDependents(wb, ...)`
JavaScript SDK	`wb.getCellDependents(address: string, depth: number \| typeof Infinity = 1)`
Python SDK	`wb.get_cell_dependents(address: CellRef, depth: int \| float = 1)`

Signature

async function getCellDependents(wb: WorkbookContext, address: string, depth: number | typeof Infinity = 1): Promise<{
  cells: {
    address: string;
    depth: number;
    formula?: string;
    referenceType?: 'direct' | 'range' | 'named' | 'table';
  }[];
  warnings?: {
    code: string;
    address: string;
    detail?: string;
    formula?: string;
  }[];
}>

traceToInputs

Trace a cell to its input sources.

@param address - Cell address @returns Array of input traces

Surface	Call
Exec	`await xlsx.traceToInputs(wb, ...)`
JavaScript SDK	`wb.traceToInputs(address: string)`
Python SDK	`wb.trace_to_inputs(cell: CellRef)`

Signature

async function traceToInputs(wb: WorkbookContext, address: string): Promise<{
  address: string;
  referenceCount: number;
  text?: string;
  nearbyLabel?: string;
  context?: string;
}[]>

traceToOutputs

Trace a cell to its output destinations.

@param address - Cell address @returns Array of output traces

Surface	Call
Exec	`await xlsx.traceToOutputs(wb, ...)`
JavaScript SDK	`wb.traceToOutputs(address: string)`
Python SDK	`wb.trace_to_outputs(cell: CellRef)`

Signature

async function traceToOutputs(wb: WorkbookContext, address: string): Promise<{
  address: string;
  formula?: string;
  text?: string;
  visibility: 'visible' | 'outsidePrintArea' | 'collapsed' | 'hidden';
  nearbyLabel?: string;
  context?: string;
}[]>

sweepInputs

Run a sweep over input combinations and capture outputs.

@param inputs - Array of input specifications with addresses and values @param outputs - Array of output cell addresses @param options - Sweep options @returns Sweep result with all combinations

Surface	Call
Exec	`await xlsx.sweepInputs(wb, ...)`
JavaScript SDK	`wb.sweepInputs(inputs: SweepInput[], outputs: string[], options: { mode?: SweepMode; includeStats?: boolean } = {})`
Python SDK	`wb.sweep_inputs(inputs: Sequence[JsonMapping], outputs: Sequence[str \| CellRef], mode: Literal["cartesian", "parallel"] \| None = None, include_stats: bool \| None = None)`

Signature

async function sweepInputs(wb: WorkbookContext, inputs: SweepInput[], outputs: string[], options: { mode?: SweepMode; includeStats?: boolean } = {}): Promise<{
  tsv: string;
  sweeps: {
    inputs: {
      [key: string]: string;
    };
    outputs: {
      [key: string]: string;
    };
    errors: {
      code: string;
      address: string;
      detail?: string;
      formula?: string;
    }[];
  }[];
  stats?: {
    [key: string]: {
    min: number;
    max: number;
    mean: number;
    count: number;
  };
  };
  sweepCount: number;
  inputCount: number;
  outputCount: number;
}>

Verification and rendering

lint

Run linting rules on the workbook.

@param options - Lint options @returns Lint result with diagnostics

Surface	Call
Exec	`await xlsx.lint(wb, ...)`
JavaScript SDK	`wb.lint(options: { rangeAddresses?: string[]; skipRuleIds?: string[]; onlyRuleIds?: string[]; } = {})`
Python SDK	`wb.lint(range_addresses: Sequence[str] \| None = None, skip_rule_ids: Sequence[str] \| None = None, only_rule_ids: Sequence[str] \| None = None)`

Signature

async function lint(wb: WorkbookContext, options: { rangeAddresses?: string[]; skipRuleIds?: string[]; onlyRuleIds?: string[]; } = {}): Promise<{
  diagnostics: {
    severity: 'Info' | 'Warning' | 'Error';
    ruleId: string;
    message: string;
    location: string | null;
    visibility: 'visible' | 'outsidePrintArea' | 'collapsed' | 'hidden' | null;
  }[];
  total: number;
}>

previewStyles

Generate a preview image of cell styles.

@param range - Range address to preview @returns Data URL of the preview image

Surface	Call
Exec	`await xlsx.previewStyles(wb, ...)`
JavaScript SDK	`wb.previewStyles(range: string)`
Python SDK	`wb.preview_styles(range: RangeRef)`

Signature

async function previewStyles(wb: WorkbookContext, range: string): Promise<string>

Utilities

reduceAddresses

Reduce a list of addresses to minimal non-overlapping ranges.

@param addresses - Array of cell or range addresses @returns Array of reduced addresses

Surface	Call
Exec	`await xlsx.reduceAddresses(wb, ...)`
JavaScript SDK	`wb.reduceAddresses(addresses: string[])`
Python SDK	`wb.reduce_addresses(addresses: Sequence[CellRef \| RangeRef])`

Signature

async function reduceAddresses(wb: WorkbookContext, addresses: string[]): Promise<string[]>

CLI

pptx API