Edit

Share via

Get a range using the Excel JavaScript API

  • Article

This article provides examples that show different ways to get a range within a worksheet using the Excel JavaScript API. For the complete list of properties and methods that the Range object supports, see Excel.Range class.

Note

The Excel JavaScript API doesn't have a "Cell" object or class. Instead, the Excel JavaScript API defines all Excel cells as Range objects. An individual cell in the Excel UI translates to a Range object with one cell in the Excel JavaScript API. A single Range object can also contain multiple contiguous cells. See Work with cells using the Excel JavaScript API to learn more.

Get range by address

The following code sample gets the range with address B2:C5 from the worksheet named Sample, loads its address property, and writes a message to the console.

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getItem("Sample");
    
    let range = sheet.getRange("B2:C5");
    range.load("address");
    await context.sync();
    
    console.log(`The address of the range B2:C5 is "${range.address}"`);
});

Get range by name

The following code sample gets the range named MyRange from the worksheet named Sample, loads its address property, and writes a message to the console.

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getItem("Sample");

    let range = sheet.getRange("MyRange");
    range.load("address");
    await context.sync();

    console.log(`The address of the range "MyRange" is "${range.address}"`);
});

Get used range

The following code sample gets the used range from the worksheet named Sample, loads its address property, and writes a message to the console. The used range is the smallest range that encompasses any cells in the worksheet that have a value or formatting assigned to them. If the entire worksheet is blank, the getUsedRange() method returns a range that consists of only the top-left cell.

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getItem("Sample");

    let range = sheet.getUsedRange();
    range.load("address");
    await context.sync();
    
    console.log(`The address of the used range in the worksheet is "${range.address}"`);
});

Get entire range

The following code sample gets the entire worksheet range from the worksheet named Sample, loads its address property, and writes a message to the console.

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getItem("Sample");

    let range = sheet.getRange();
    range.load("address");
    await context.sync();
    
    console.log(`The address of the entire worksheet range is "${range.address}"`);
});

See also