Cell Values and Annotations

Use cell value APIs for direct worksheet content: raw values, formulas, display text, number-format metadata, notes, hyperlinks, and threaded comments. For broad discovery workflows, see Search and Discovery. For full style objects, see Styles and Layout.

Typed Reads

readCell, readRange, readRow, and readColumn return typed cell objects:

const cell = await xlsx.readCell(wb, "Summary!B5", { context: 2 })

Each returned cell includes its address, coordinates, raw value, optional formula, Excel-like type, display text, optional number format, inferred numberType, visibility, and optional surrounding context.

Read results also include cell annotations when present:

Compact Reads

Use TSV reads when a script needs dense workbook text without full JSON cell objects:

const tsv = await xlsx.readRangeTsv(wb, "Summary!A1:F40", {
  includeFormulas: true
})

readRangeTsv, readRowTsv, and readColumnTsv preserve cell coordinates in the TSV output. Use JSON reads when you need raw values, formulas, annotations, visibility, or number-format metadata.

Writes

setCells writes one or more cell payloads:

const result = await xlsx.setCells(wb, [
  { address: "Inputs!A1", value: "Revenue" },
  { address: "Inputs!B1", value: 1250000 },
  { address: "Inputs!C1", formula: "=B1*1.1", format: "$#,##0" }
])

Formula-affecting writes recalculate downstream formulas before returning. The result includes:

• touched: recalculated display text by address.
• changed: directly changed cells plus recalculated cells whose value changed.
• errors: new formula errors introduced by the write.
• invalidatedTiles and updatedSheets: render-cache and used-range metadata for UI workflows.

Pass validationMode: "reject" when writes should fail if they violate existing Data Validation rules:

await xlsx.setCells(
  wb,
  [{ address: "Inputs!B5", value: -10 }],
  { validationMode: "reject" }
)

Notes And Hyperlinks

Set, replace, or clear legacy Excel notes and hyperlinks through setCells:

await xlsx.setCells(wb, [
  {
    address: "Summary!A1",
    value: "Model assumptions",
    note: { author: "Finance", text: "Review before board pack." },
    link: { ref: "Inputs!A1", tooltip: "Jump to inputs" }
  },
  {
    address: "Summary!A2",
    link: { url: "https://example.com/report", tooltip: "Source report" }
  }
])

Pass note: null or link: null to clear the existing annotation. Hyperlinks can target either an external URL or an internal workbook reference.

Threaded Comments

Threaded comments are represented in normal cell reads and writes:

await xlsx.setCells(wb, [
  {
    address: "Summary!B5",
    thread: {
      add: [{ author: "Analyst", text: "Updated for latest forecast." }],
      resolved: false
    }
  }
])

Use thread: null or { delete: true } to remove the thread. Set resolved: true or resolved: false to update the thread state.

Excel notes and threaded comments are separate annotation types. A cell cannot have both a legacy note and a threaded comment at the same time; remove one before adding the other.

Array And Data-Table Cells

setCells follows Excel's structural rules around formula blocks:

• Cells inside a What-If Data Table cannot be edited directly; delete and recreate the data table instead.
• Cells inside a multi-cell legacy CSE array formula cannot be edited directly.
• Editing a dynamic-array spill child collapses the existing spill and recalculates the array formula so it can reassert.

See Calc for formula behavior and What-If Analysis for data tables.

See xlsx API for read signatures and Writing and structure for setCells.