Excel. Range class

Used by

Excel.Application: union
Excel.AutoFilter: apply, getRange, getRangeOrNullObject
Excel.BasicDataValidation: formula1, formula2
Excel.Binding: getRange
Excel.BindingCollection: add
Excel.Chart: setData, setPosition
Excel.ChartAxis: setCategoryNames
Excel.ChartCollection: add
Excel.ChartSeries: setBubbleSizes, setValues, setXAxisValues
Excel.Comment: getLocation
Excel.CommentCollection: add, getItemByCell
Excel.CommentReply: getLocation
Excel.ConditionalFormat: getRange, getRangeOrNullObject, setRanges
Excel.DateTimeDataValidation: formula1, formula2
Excel.Functions: abs, accrInt, accrIntM, acos, acosh, acot, acoth, amorDegrc, amorLinc, and, arabic, areas, asc, asin, asinh, atan, atan2, atanh, aveDev, average, averageA, averageIf, averageIfs, bahtText, base, besselI, besselJ, besselK, besselY, beta_Dist, beta_Inv, bin2Dec, bin2Hex, bin2Oct, binom_Dist, binom_Dist_Range, binom_Inv, bitand, bitlshift, bitor, bitrshift, bitxor, ceiling_Math, ceiling_Precise, char, chiSq_Dist, chiSq_Dist_RT, chiSq_Inv, chiSq_Inv_RT, choose, clean, code, columns, combin, combina, complex, concatenate, confidence_Norm, confidence_T, convert, cos, cosh, cot, coth, count, countA, countBlank, countIf, countIfs, coupDayBs, coupDays, coupDaysNc, coupNcd, coupNum, coupPcd, csc, csch, cumIPmt, cumPrinc, date, datevalue, daverage, day, days, days360, db, dbcs, dcount, dcountA, ddb, dec2Bin, dec2Hex, dec2Oct, decimal, degrees, delta, devSq, dget, disc, dmax, dmin, dollar, dollarDe, dollarFr, dproduct, dstDev, dstDevP, dsum, duration, dvar, dvarP, ecma_Ceiling, edate, effect, eoMonth, erf, erf_Precise, erfC, erfC_Precise, error_Type, even, exact, exp, expon_Dist, f_Dist, f_Dist_RT, f_Inv, f_Inv_RT, fact, factDouble, find, findB, fisher, fisherInv, fixed, floor_Math, floor_Precise, fv, fvschedule, gamma, gamma_Dist, gamma_Inv, gammaLn, gammaLn_Precise, gauss, gcd, geoMean, geStep, harMean, hex2Bin, hex2Dec, hex2Oct, hlookup, hour, hyperlink, hypGeom_Dist, if, imAbs, imaginary, imArgument, imConjugate, imCos, imCosh, imCot, imCsc, imCsch, imDiv, imExp, imLn, imLog10, imLog2, imPower, imProduct, imReal, imSec, imSech, imSin, imSinh, imSqrt, imSub, imSum, imTan, int, intRate, ipmt, irr, isErr, isError, isEven, isFormula, isLogical, isNA, isNonText, isNumber, iso_Ceiling, isOdd, isoWeekNum, ispmt, isref, isText, kurt, large, lcm, left, leftb, len, lenb, ln, log, log10, logNorm_Dist, logNorm_Inv, lookup, lower, match, max, maxA, mduration, median, mid, midb, min, minA, minute, mirr, mod, month, mround, multiNomial, n, negBinom_Dist, networkDays, networkDays_Intl, nominal, norm_Dist, norm_Inv, norm_S_Dist, norm_S_Inv, not, nper, npv, numberValue, oct2Bin, oct2Dec, oct2Hex, odd, oddFPrice, oddFYield, oddLPrice, oddLYield, or, pduration, percentile_Exc, percentile_Inc, percentRank_Exc, percentRank_Inc, permut, permutationa, phi, pmt, poisson_Dist, power, ppmt, price, priceDisc, priceMat, product, proper, pv, quartile_Exc, quartile_Inc, quotient, radians, randBetween, rank_Avg, rank_Eq, rate, received, replace, replaceB, rept, right, rightb, roman, round, roundDown, roundUp, rows, rri, sec, sech, second, seriesSum, sheet, sheets, sign, sin, sinh, skew, skew_p, sln, small, sqrt, sqrtPi, standardize, stDev_P, stDev_S, stDevA, stDevPA, substitute, subtotal, sum, sumIf, sumIfs, sumSq, syd, t, t_Dist, t_Dist_2T, t_Dist_RT, t_Inv, t_Inv_2T, tan, tanh, tbillEq, tbillPrice, tbillYield, text, time, timevalue, trim, trimMean, trunc, type, unichar, unicode, upper, usdollar, value, var_P, var_S, varA, varPA, vdb, vlookup, weekday, weekNum, weibull_Dist, workDay, workDay_Intl, xirr, xnpv, xor, year, yearFrac, yield, yieldDisc, yieldMat, z_Test
Excel.ListDataValidation: source
Excel.NamedItem: getRange, getRangeOrNullObject
Excel.NamedItemCollection: add
Excel.Note: getLocation
Excel.NoteCollection: add
Excel.PageBreak: getCellAfterBreak
Excel.PageBreakCollection: add
Excel.PageLayout: getPrintTitleColumns, getPrintTitleColumnsOrNullObject, getPrintTitleRows, getPrintTitleRowsOrNullObject, setPrintArea, setPrintTitleColumns, setPrintTitleRows
Excel.PivotLayout: getCell, getColumnLabelRange, getDataBodyRange, getDataHierarchy, getFilterAxisRange, getPivotItems, getRange, getRowLabelRange, setAutoSortOnCell
Excel.PivotTableCollection: add
Excel.RangeAreas: copyFrom, getIntersection, getIntersectionOrNullObject
Excel.RangeCollection: getItemAt, items
Excel.RangeView: getRange
Excel.Table: convertToRange, getDataBodyRange, getHeaderRowRange, getRange, getTotalRowRange, resize
Excel.TableChangedEventArgs: getRange, getRangeOrNullObject
Excel.TableCollection: add
Excel.TableColumn: getDataBodyRange, getHeaderRowRange, getRange, getTotalRowRange
Excel.TableRow: getRange
Excel.Window: activeCell, visibleRange
Excel.Workbook: getActiveCell, getSelectedRange
Excel.Worksheet: getCell, getRange, getRangeByIndexes, getUsedRange, getUsedRangeOrNullObject
Excel.WorksheetChangedEventArgs: getRange, getRangeOrNullObject
Excel.WorksheetFormatChangedEventArgs: getRange, getRangeOrNullObject
Excel.WorksheetFreezePanes: freezeAt, getLocation, getLocationOrNullObject

Examples

// Get a Range object by its address.
await Excel.run(async (context) => {
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const worksheet = context.workbook.worksheets.getItem(sheetName);
    const range = worksheet.getRange(rangeAddress);
    const cell = range.getCell(0,0);
    cell.load('address');
    await context.sync();
    
    console.log(cell.address);
});

Properties

address	Specifies the range reference in A1-style. Address value contains the sheet reference (e.g., "Sheet1!A1:B4").
addressLocal	Represents the range reference for the specified range in the language of the user.
cellCount	Specifies the number of cells in the range. This API will return -1 if the cell count exceeds 2^31-1 (2,147,483,647).
columnCount	Specifies the total number of columns in the range.
columnHidden	Represents if all columns in the current range are hidden. Value is `true` when all columns in a range are hidden. Value is `false` when no columns in the range are hidden. Value is `null` when some columns in a range are hidden and other columns in the same range are not hidden.
columnIndex	Specifies the column number of the first cell in the range. Zero-indexed.
conditionalFormats	The collection of `ConditionalFormats` that intersect the range.
context	The request context associated with the object. This connects the add-in's process to the Office host application's process.
control	Accesses the cell control applied to this range. If the range has multiple cell controls, this returns `EmptyCellControl`.
dataValidation	Returns a data validation object.
format	Returns a format object, encapsulating the range's font, fill, borders, alignment, and other properties.
formulaArray	Specifies the array formula of a range. If the specified range doesn't contain an array formula, this property returns `null`.
formulas	Represents the formula in A1-style notation. If a cell has no formula, its value is returned instead.
formulasLocal	Represents the formula in A1-style notation, in the user's language and number-formatting locale. For example, the English "=SUM(A1, 1.5)" formula would become "=SUMME(A1; 1,5)" in German. If a cell has no formula, its value is returned instead.
formulasR1C1	Represents the formula in R1C1-style notation. If a cell has no formula, its value is returned instead.
hasSpill	Represents if all cells have a spill border. Returns `true` if all cells have a spill border, or `false` if all cells do not have a spill border. Returns `null` if there are cells both with and without spill borders within the range.
height	Returns the distance in points, for 100% zoom, from the top edge of the range to the bottom edge of the range.
hidden	Represents if all cells in the current range are hidden. Value is `true` when all cells in a range are hidden. Value is `false` when no cells in the range are hidden. Value is `null` when some cells in a range are hidden and other cells in the same range are not hidden.
hyperlink	Represents the hyperlink for the current range.
isEntireColumn	Represents if the current range is an entire column.
isEntireRow	Represents if the current range is an entire row.
left	Returns the distance in points, for 100% zoom, from the left edge of the worksheet to the left edge of the range.
linkedDataTypeState	Represents the data type state of each cell.
numberFormat	Represents Excel's number format code for the given range. For more information about Excel number formatting, see Number format codes.
numberFormatCategories	Represents the category of number format of each cell.
numberFormatLocal	Represents Excel's number format code for the given range, based on the language settings of the user. Excel does not perform any language or format coercion when getting or setting the `numberFormatLocal` property. Any returned text uses the locally-formatted strings based on the language specified in the system settings.
rowCount	Returns the total number of rows in the range.
rowHidden	Represents if all rows in the current range are hidden. Value is `true` when all rows in a range are hidden. Value is `false` when no rows in the range are hidden. Value is `null` when some rows in a range are hidden and other rows in the same range are not hidden.
rowIndex	Returns the row number of the first cell in the range. Zero-indexed.
savedAsArray	Represents if all the cells would be saved as an array formula. Returns `true` if all cells would be saved as an array formula, or `false` if all cells would not be saved as an array formula. Returns `null` if some cells would be saved as an array formula and some would not be.
sort	Represents the range sort of the current range.
style	Represents the style of the current range. If the styles of the cells are inconsistent, `null` will be returned. For custom styles, the style name will be returned. For built-in styles, a string representing a value in the `BuiltInStyle` enum will be returned.
text	Text values of the specified range. The text value will not depend on the cell width. The number sign (#) substitution that happens in the Excel UI will not affect the text value returned by the API.
top	Returns the distance in points, for 100% zoom, from the top edge of the worksheet to the top edge of the range.
values	Represents the raw values of the specified range. The data returned could be a string, number, or Boolean. Cells that contain an error will return the error string. If the returned value starts with a plus ("+"), minus ("-"), or equal sign ("="), Excel interprets this value as a formula. Locale-shaped strings (such as the date "19-8-2025" in nl-NL or fr-FR, format DD-MM-YYYY) are stored as text instead of as dates. To ensure dates are stored as dates, use a locale-aware API like `formulasLocal` or use a locale-neutral format like ISO (YYYY-MM-DD) or a numeric date serial.
valuesAsJson	A JSON representation of the values in the cells in this range. Unlike `Range.values`, `Range.valuesAsJson` supports all data types which can be in a cell. Examples include formatted number values and web images, in addition to the standard Boolean, number, and string values. Data returned from this API always aligns with the en-US locale. To retrieve data in the user's display locale, use `Range.valuesAsJsonLocal`.
valuesAsJsonLocal	A JSON representation of the values in the cells in this range. Unlike `Range.values`, `Range.valuesAsJsonLocal` supports all data types which can be in a cell. Examples include formatted number values and web images, in addition to the standard Boolean, number, and string values. Data returned from this API always aligns with the user's display locale. To retrieve data independent of locale, use `Range.valuesAsJson`.
valueTypes	Specifies the type of data in each cell.
width	Returns the distance in points, for 100% zoom, from the left edge of the range to the right edge of the range.
worksheet	The worksheet containing the current range.

Methods

autoFill(destinationRange, autoFillType)	Fills a range from the current range to the destination range using the specified AutoFill logic. The destination range can be `null` or can extend the source range either horizontally or vertically. Discontiguous ranges are not supported. For more information, see Use AutoFill and Flash Fill.
autoFill(destinationRange, autoFillType)	Fills a range from the current range to the destination range using the specified AutoFill logic. The destination range can be `null` or can extend the source range either horizontally or vertically. Discontiguous ranges are not supported. For more information, see Use AutoFill and Flash Fill.
calculate()	Calculates a range of cells on a worksheet.
checkSpelling(options)	Checks the spelling of words in this range. This method opens the Spelling dialog box in the Excel UI.
clear(applyTo)	Clear range values and formatting, such as fill and border.
clear(applyTo)	Clear range values and formatting, such as fill and border.
clearOrResetContents()	Clears the values of the cells in the range, with special consideration given to cells containing controls. If the range contains only blank values and controls set to their default value, then the values and control formatting are removed. Otherwise, this sets the cells with controls to their default value and clears the values of the other cells in the range.
convertDataTypeToText()	Converts the range cells with data types into text.
convertToLinkedDataType(serviceID, languageCulture)	Converts the range cells into linked data types in the worksheet.
copyFrom(sourceRange, copyType, skipBlanks, transpose)	Copies cell data or formatting from the source range or `RangeAreas` to the current range. The destination range can be a different size than the source range or `RangeAreas`. The destination is expanded automatically if it's smaller than the source. Note: Like the copy functionality in the Excel UI, if the destination range is an exact multiple greater than the source range in either rows or columns, then the source content is replicated multiple times. For example, a 2x2 range copy into a 2x6 range will result in 3 copies of the original 2x2 range.
copyFrom(sourceRange, copyType, skipBlanks, transpose)	Copies cell data or formatting from the source range or `RangeAreas` to the current range. The destination range can be a different size than the source range or `RangeAreas`. The destination is expanded automatically if it's smaller than the source. Note: Like the copy functionality in the Excel UI, if the destination range is an exact multiple greater than the source range in either rows or columns, then the source content is replicated multiple times. For example, a 2x2 range copy into a 2x6 range will result in 3 copies of the original 2x2 range.
delete(shift)	Deletes the cells associated with the range.
delete(shift)	Deletes the cells associated with the range.
find(text, criteria)	Finds the given string based on the criteria specified. If the current range is larger than a single cell, then the search will be limited to that range, else the search will cover the entire sheet starting after that cell.
findOrNullObject(text, criteria)	Finds the given string based on the criteria specified. If the current range is larger than a single cell, then the search will be limited to that range, else the search will cover the entire sheet starting after that cell. If there are no matches, then this method returns an object with its `isNullObject` property set to `true`. For further information, see *OrNullObject methods and properties.
flashFill()	Does a Flash Fill to the current range. Flash Fill automatically fills data when it senses a pattern, so the range must be a single column range and have data around it in order to find a pattern.
getAbsoluteResizedRange(numRows, numColumns)	Gets a `Range` object with the same top-left cell as the current `Range` object, but with the specified numbers of rows and columns.
getBoundingRect(anotherRange)	Gets the smallest range object that encompasses the given ranges. For example, the `GetBoundingRect` of "B2:C5" and "D10:E15" is "B2:E15".
getCell(row, column)	Gets the range object containing the single cell based on row and column numbers. The cell can be outside the bounds of its parent range, so long as it stays within the worksheet grid. The returned cell is located relative to the top left cell of the range.
getCellProperties(cellPropertiesLoadOptions)	Returns a 2D array, encapsulating the data for each cell's font, fill, borders, alignment, and other properties.
getColumn(column)	Gets a column contained in the range.
getColumnProperties(columnPropertiesLoadOptions)	Returns a single-dimensional array, encapsulating the data for each column's font, fill, borders, alignment, and other properties. For properties that are not consistent across each cell within a given column, null will be returned.
getColumnsAfter(count)	Gets a certain number of columns to the right of the current `Range` object.
getColumnsBefore(count)	Gets a certain number of columns to the left of the current `Range` object.
getDependents()	Returns a `WorkbookRangeAreas` object that represents the range containing all the dependent cells of a specified range in the same worksheet or across multiple worksheets. Throws an `ItemNotFound` error if no dependents are found.
getDirectDependents()	Returns a `WorkbookRangeAreas` object that represents the range containing all the direct dependent cells of a specified range in the same worksheet or across multiple worksheets. Throws an `ItemNotFound` error if no dependents are found.
getDirectPrecedents()	Returns a `WorkbookRangeAreas` object that represents the range containing all the direct precedent cells of a specified range in the same worksheet or across multiple worksheets. Throws an `ItemNotFound` error if no precedents are found.
getDisplayedCellProperties(cellPropertiesLoadOptions)	Returns a 2D array, encapsulating the display data for each cell's font, fill, borders, alignment, and other properties. Unlike `getCellProperties`, which only shows properties that are set directly for the cell, this returns properties that are displayed from indirect sources, such as conditional formatting or styles.
getEntireColumn()	Gets an object that represents the entire column of the range (for example, if the current range represents cells "B4:E11", its `getEntireColumn` is a range that represents columns "B:E").
getEntireRow()	Gets an object that represents the entire row of the range (for example, if the current range represents cells "B4:E11", its `GetEntireRow` is a range that represents rows "4:11").
getExtendedRange(direction, activeCell)	Returns a range object that includes the current range and up to the edge of the range, based on the provided direction. This matches the Ctrl+Shift+Arrow key behavior in the Excel on Windows UI.
getExtendedRange(direction, activeCell)	Returns a range object that includes the current range and up to the edge of the range, based on the provided direction. This matches the Ctrl+Shift+Arrow key behavior in the Excel on Windows UI.
getImage()	Renders the range as a Base64-encoded PNG image.
getIntersection(anotherRange)	Gets the range object that represents the rectangular intersection of the given ranges.
getIntersectionOrNullObject(anotherRange)	Gets the range object that represents the rectangular intersection of the given ranges. If no intersection is found, then this method returns an object with its `isNullObject` property set to `true`. For further information, see *OrNullObject methods and properties.
getLastCell()	Gets the last cell within the range. For example, the last cell of "B2:D5" is "D5".
getLastColumn()	Gets the last column within the range. For example, the last column of "B2:D5" is "D2:D5".
getLastRow()	Gets the last row within the range. For example, the last row of "B2:D5" is "B5:D5".
getMergedAreasOrNullObject()	Returns a `RangeAreas` object that represents the merged areas in this range. Note that if the merged areas count in this range is more than 512, then this method will fail to return the result. If the `RangeAreas` object doesn't exist, then this method returns an object with its `isNullObject` property set to `true`. For further information, see *OrNullObject methods and properties.
getOffsetRange(rowOffset, columnOffset)	Gets an object which represents a range that's offset from the specified range. The dimension of the returned range will match this range. If the resulting range is forced outside the bounds of the worksheet grid, an error will be thrown.
getPivotTables(fullyContained)	Gets a scoped collection of PivotTables that overlap with the range.
getPrecedents()	Returns a `WorkbookRangeAreas` object that represents the range containing all the precedent cells of a specified range in the same worksheet or across multiple worksheets. Throws an `ItemNotFound` error if no precedents are found.
getRangeEdge(direction, activeCell)	Returns a range object that is the edge cell of the data region that corresponds to the provided direction. This matches the Ctrl+Arrow key behavior in the Excel on Windows UI.
getRangeEdge(direction, activeCell)	Returns a range object that is the edge cell of the data region that corresponds to the provided direction. This matches the Ctrl+Arrow key behavior in the Excel on Windows UI.
getResizedRange(deltaRows, deltaColumns)	Gets a `Range` object similar to the current `Range` object, but with its bottom-right corner expanded (or contracted) by some number of rows and columns.
getRow(row)	Gets a row contained in the range.
getRowProperties(rowPropertiesLoadOptions)	Returns a single-dimensional array, encapsulating the data for each row's font, fill, borders, alignment, and other properties. For properties that are not consistent across each cell within a given row, `null` will be returned.
getRowsAbove(count)	Gets a certain number of rows above the current `Range` object.
getRowsBelow(count)	Gets a certain number of rows below the current `Range` object.
getSpecialCells(cellType, cellValueType)	Gets the `RangeAreas` object, comprising one or more rectangular ranges, that represents all the cells that match the specified type and value. If no special cells are found, an `ItemNotFound` error will be thrown.
getSpecialCells(cellType, cellValueType)	Gets the `RangeAreas` object, comprising one or more rectangular ranges, that represents all the cells that match the specified type and value. If no special cells are found, an `ItemNotFound` error will be thrown.
getSpecialCellsOrNullObject(cellType, cellValueType)	Gets the `RangeAreas` object, comprising one or more ranges, that represents all the cells that match the specified type and value. If no special cells are found, then this method returns an object with its `isNullObject` property set to `true`. For further information, see *OrNullObject methods and properties.
getSpecialCellsOrNullObject(cellType, cellValueType)	Gets the `RangeAreas` object, comprising one or more ranges, that represents all the cells that match the specified type and value. If no special cells are found, then this method returns an object with its `isNullObject` property set to `true`. For further information, see *OrNullObject methods and properties.
getSpillingToRange()	Gets the range object containing the spill range when called on an anchor cell. Fails if applied to a range with more than one cell.
getSpillingToRangeOrNullObject()	Gets the range object containing the spill range when called on an anchor cell. If the range isn't an anchor cell or the spill range can't be found, then this method returns an object with its `isNullObject` property set to `true`. For further information, see *OrNullObject methods and properties.
getSpillParent()	Gets the range object containing the anchor cell for a cell getting spilled into. Fails if applied to a range with more than one cell.
getSpillParentOrNullObject()	Gets the range object containing the anchor cell for the cell getting spilled into. If it's not a spilled cell, or more than one cell is given, then this method returns an object with its `isNullObject` property set to `true`. For further information, see *OrNullObject methods and properties.
getSurroundingRegion()	Returns a `Range` object that represents the surrounding region for the top-left cell in this range. A surrounding region is a range bounded by any combination of blank rows and blank columns relative to this range.
getTables(fullyContained)	Gets a scoped collection of tables that overlap with the range.
getUsedRange(valuesOnly)	Returns the used range of the given range object. If there are no used cells within the range, this function will throw an `ItemNotFound` error.
getUsedRangeOrNullObject(valuesOnly)	Returns the used range of the given range object. If there are no used cells within the range, then this method returns an object with its `isNullObject` property set to `true`. For further information, see *OrNullObject methods and properties.
getVisibleView()	Represents the visible rows of the current range.
group(groupOption)	Groups columns and rows for an outline.
group(groupOption)	Groups columns and rows for an outline.
hideGroupDetails(groupOption)	Hides the details of the row or column group.
hideGroupDetails(groupOption)	Hides the details of the row or column group.
insert(shift)	Inserts a cell or a range of cells into the worksheet in place of this range, and shifts the other cells to make space. Returns a new `Range` object at the now blank space.
insert(shift)	Inserts a cell or a range of cells into the worksheet in place of this range, and shifts the other cells to make space. Returns a new `Range` object at the now blank space.
load(options)	Queues up a command to load the specified properties of the object. You must call `context.sync()` before reading the properties.
load(propertyNames)	Queues up a command to load the specified properties of the object. You must call `context.sync()` before reading the properties.
load(propertyNamesAndPaths)	Queues up a command to load the specified properties of the object. You must call `context.sync()` before reading the properties.
merge(across)	Merge the range cells into one region in the worksheet.
moveTo(destinationRange)	Moves cell values, formatting, and formulas from current range to the destination range, replacing the old information in those cells. The destination range will be expanded automatically if it is smaller than the current range. Any cells in the destination range that are outside of the original range's area are not changed. Note: When a range is moved to a new address using this API, the new range object should be retrieved using the new address.
removeDuplicates(columns, includesHeader)	Removes duplicate values from the range specified by the columns.
replaceAll(text, replacement, criteria)	Finds and replaces the given string based on the criteria specified within the current range.
select()	Selects the specified range in the Excel UI.
set(properties, options)	Sets multiple properties of an object at the same time. You can pass either a plain object with the appropriate properties, or another API object of the same type.
set(properties)	Sets multiple properties on the object at the same time, based on an existing loaded object.
setCellProperties(cellPropertiesData)	Updates the range based on a 2D array of cell properties, encapsulating things like font, fill, borders, and alignment.
setColumnProperties(columnPropertiesData)	Updates the range based on a single-dimensional array of column properties, encapsulating things like font, fill, borders, and alignment.
setDirty()	Set a range to be recalculated when the next recalculation occurs.
setRowProperties(rowPropertiesData)	Updates the range based on a single-dimensional array of row properties, encapsulating things like font, fill, borders, and alignment.
showCard()	Displays the card for an active cell if it has rich value content.
showDependents(remove)	Draws tracer arrows to the direct dependents of the range.
showGroupDetails(groupOption)	Shows the details of the row or column group.
showGroupDetails(groupOption)	Shows the details of the row or column group.
showPrecedents(remove)	Draws tracer arrows to the direct precedents of the range.
togglePythonMarshalMode(marshalMode)	Sets the marshaling mode of the Python in Excel formula =PY.
togglePythonMarshalMode(marshalMode)	Sets the marshaling mode of the Python in Excel formula =PY.
toJSON()	Overrides the JavaScript `toJSON()` method in order to provide more useful output when an API object is passed to `JSON.stringify()`. (`JSON.stringify`, in turn, calls the `toJSON` method of the object that's passed to it.) Whereas the original `Excel.Range` object is an API object, the `toJSON` method returns a plain JavaScript object (typed as `Excel.Interfaces.RangeData`) that contains shallow copies of any loaded child properties from the original object.
track()	Track the object for automatic adjustment based on surrounding changes in the document. This call is a shorthand for context.trackedObjects.add(thisObject). If you're using this object across `.sync` calls and outside the sequential execution of a ".run" batch, and get an "InvalidObjectPath" error when setting a property or invoking a method on the object, you need to add the object to the tracked object collection when the object was first created.
ungroup(groupOption)	Ungroups columns and rows for an outline.
ungroup(groupOption)	Ungroups columns and rows for an outline.
unmerge()	Unmerge the range cells into separate cells.
untrack()	Release the memory associated with this object, if it has previously been tracked. This call is shorthand for context.trackedObjects.remove(thisObject). Having many tracked objects slows down the host application, so please remember to free any objects you add, once you're done using them. You'll need to call `context.sync()` before the memory release takes effect.

Property Details

address

Specifies the range reference in A1-style. Address value contains the sheet reference (e.g., "Sheet1!A1:B4").

readonly address: string;

Property Value

string

Remarks

addressLocal

Represents the range reference for the specified range in the language of the user.

readonly addressLocal: string;

Property Value

string

Remarks

cellCount

Specifies the number of cells in the range. This API will return -1 if the cell count exceeds 2^31-1 (2,147,483,647).

readonly cellCount: number;

Property Value

number

Remarks

columnCount

Specifies the total number of columns in the range.

readonly columnCount: number;

Property Value

number

Remarks

columnHidden

Represents if all columns in the current range are hidden. Value is true when all columns in a range are hidden. Value is false when no columns in the range are hidden. Value is null when some columns in a range are hidden and other columns in the same range are not hidden.

columnHidden: boolean;

Property Value

boolean

Remarks

columnIndex

Specifies the column number of the first cell in the range. Zero-indexed.

readonly columnIndex: number;

Property Value

number

Remarks

conditionalFormats

The collection of ConditionalFormats that intersect the range.

readonly conditionalFormats: Excel.ConditionalFormatCollection;

Property Value

Excel.ConditionalFormatCollection

Remarks

API set: ExcelApi 1.6

context

The request context associated with the object. This connects the add-in's process to the Office host application's process.

context: RequestContext;

Property Value

Excel.RequestContext

control

Accesses the cell control applied to this range. If the range has multiple cell controls, this returns EmptyCellControl.

control: CellControl;

Property Value

Excel.CellControl

Remarks

API set: ExcelApi 1.18

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-cell-control.yaml

// Add checkboxes to the table.
await Excel.run(async (context) => {
  const sheet = context.workbook.worksheets.getActiveWorksheet();

  // Get the second column in the table, without the header.
  const range = sheet.tables.getItem("FruitTable").columns.getItem("Analysis").getDataBodyRange();

  // Change the boolean values to checkboxes.
  range.control = {
    type: Excel.CellControlType.checkbox
  };
  await context.sync();
});

dataValidation

Returns a data validation object.

readonly dataValidation: Excel.DataValidation;

Property Value

Excel.DataValidation

Remarks

API set: ExcelApi 1.8

format

Returns a format object, encapsulating the range's font, fill, borders, alignment, and other properties.

readonly format: Excel.RangeFormat;

Property Value

Excel.RangeFormat

Remarks

API set: ExcelApiDesktop 1.1

formulaArray

Specifies the array formula of a range. If the specified range doesn't contain an array formula, this property returns null.

formulaArray: string;

Property Value

string

Remarks

formulas

Represents the formula in A1-style notation. If a cell has no formula, its value is returned instead.

formulas: any[][];

Property Value

any[][]

Remarks

formulasLocal

Represents the formula in A1-style notation, in the user's language and number-formatting locale. For example, the English "=SUM(A1, 1.5)" formula would become "=SUMME(A1; 1,5)" in German. If a cell has no formula, its value is returned instead.

formulasLocal: any[][];

Property Value

any[][]

Remarks

formulasR1C1

Represents the formula in R1C1-style notation. If a cell has no formula, its value is returned instead.

formulasR1C1: any[][];

Property Value

any[][]

Remarks

hasSpill

Represents if all cells have a spill border. Returns true if all cells have a spill border, or false if all cells do not have a spill border. Returns null if there are cells both with and without spill borders within the range.

readonly hasSpill: boolean;

Property Value

boolean

Remarks

API set: ExcelApi 1.12

height

Returns the distance in points, for 100% zoom, from the top edge of the range to the bottom edge of the range.

readonly height: number;

Property Value

number

Remarks

hidden

Represents if all cells in the current range are hidden. Value is true when all cells in a range are hidden. Value is false when no cells in the range are hidden. Value is null when some cells in a range are hidden and other cells in the same range are not hidden.

readonly hidden: boolean;

Property Value

boolean

Remarks

hyperlink

Represents the hyperlink for the current range.

hyperlink: Excel.RangeHyperlink;

Property Value

Excel.RangeHyperlink

Remarks

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-hyperlink.yaml

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

    let productsRange = sheet.getRange("A3:A5");
    productsRange.load("values");

    await context.sync();

    // Create a hyperlink to a URL 
    // for each product name in the first table.
    for (let i = 0; i < productsRange.values.length; i++) {
        let cellRange = productsRange.getCell(i, 0);
        let cellText = productsRange.values[i][0];

        let hyperlink = {
            textToDisplay: cellText,
            screenTip: "Search Bing for '" + cellText + "'",
            address: "https://www.bing.com?q=" + cellText
        }
        cellRange.hyperlink = hyperlink;
    }

    await context.sync();
});

isEntireColumn

Represents if the current range is an entire column.

readonly isEntireColumn: boolean;

Property Value

boolean

Remarks

isEntireRow

Represents if the current range is an entire row.

readonly isEntireRow: boolean;

Property Value

boolean

Remarks

left

Returns the distance in points, for 100% zoom, from the left edge of the worksheet to the left edge of the range.

readonly left: number;

Property Value

number

Remarks

linkedDataTypeState

Represents the data type state of each cell.

readonly linkedDataTypeState: Excel.LinkedDataTypeState[][];

Property Value

Excel.LinkedDataTypeState[][]

Remarks

API set: ExcelApi 1.9

numberFormat

Represents Excel's number format code for the given range. For more information about Excel number formatting, see Number format codes.

numberFormat: any[][];

Property Value

any[][]

Remarks

Examples

// Set the text of the chart title to "My Chart" and display it as an overlay on the chart.
await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "F5:G7";
    const numberFormat = [[null, "d-mmm"], [null, "d-mmm"], [null, null]]
    const values = [["Today", 42147], ["Tomorrow", "5/24"], ["Difference in days", null]];
    const formulas = [[null,null], [null,null], [null,"=G6-G5"]];
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.numberFormat = numberFormat;
    range.values = values;
    range.formulas= formulas;
    range.load('text');
    await context.sync();
    
    console.log(range.text);
});

numberFormatCategories

Represents the category of number format of each cell.

readonly numberFormatCategories: Excel.NumberFormatCategory[][];

Property Value

Excel.NumberFormatCategory[][]

Remarks

API set: ExcelApi 1.12

numberFormatLocal

Represents Excel's number format code for the given range, based on the language settings of the user. Excel does not perform any language or format coercion when getting or setting the numberFormatLocal property. Any returned text uses the locally-formatted strings based on the language specified in the system settings.

numberFormatLocal: any[][];

Property Value

any[][]

Remarks

rowCount

Returns the total number of rows in the range.

readonly rowCount: number;

Property Value

number

Remarks

rowHidden

Represents if all rows in the current range are hidden. Value is true when all rows in a range are hidden. Value is false when no rows in the range are hidden. Value is null when some rows in a range are hidden and other rows in the same range are not hidden.

rowHidden: boolean;

Property Value

boolean

Remarks

rowIndex

Returns the row number of the first cell in the range. Zero-indexed.

readonly rowIndex: number;

Property Value

number

Remarks

savedAsArray

Represents if all the cells would be saved as an array formula. Returns true if all cells would be saved as an array formula, or false if all cells would not be saved as an array formula. Returns null if some cells would be saved as an array formula and some would not be.

readonly savedAsArray: boolean;

Property Value

boolean

Remarks

API set: ExcelApi 1.12

sort

Represents the range sort of the current range.

readonly sort: Excel.RangeSort;

Property Value

Excel.RangeSort

Remarks

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/event-column-and-row-sort.yaml

async function sortTopToBottom(criteria: string) {
    await Excel.run(async (context) => {
        const sheet = context.workbook.worksheets.getActiveWorksheet();
        const range = sheet.getRange("A1:E5");

        // Find the column header that provides the sort criteria.
        const header = range.find(criteria, {});
        header.load("columnIndex");
        await context.sync();

        range.sort.apply(
            [
                {
                    key: header.columnIndex,
                    sortOn: Excel.SortOn.value
                }
            ],
            false /*matchCase*/,
            true /*hasHeaders*/,
            Excel.SortOrientation.rows
        );
        await context.sync();
    });
}

style

Represents the style of the current range. If the styles of the cells are inconsistent, null will be returned. For custom styles, the style name will be returned. For built-in styles, a string representing a value in the BuiltInStyle enum will be returned.

style: string;

Property Value

string

Remarks

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/style.yaml

await Excel.run(async (context) => {
    let worksheet = context.workbook.worksheets.getItem("Sample");
    let range = worksheet.getRange("A1:E1");

    // Apply built-in style. 
    // Styles are in the Home tab ribbon.
    range.style = Excel.BuiltInStyle.neutral;
    range.format.horizontalAlignment = "Right";

    await context.sync();
});

text

Text values of the specified range. The text value will not depend on the cell width. The number sign (#) substitution that happens in the Excel UI will not affect the text value returned by the API.

readonly text: string[][];

Property Value

string[][]

Remarks

top

Returns the distance in points, for 100% zoom, from the top edge of the worksheet to the top edge of the range.

readonly top: number;

Property Value

number

Remarks

values

Represents the raw values of the specified range. The data returned could be a string, number, or Boolean. Cells that contain an error will return the error string. If the returned value starts with a plus ("+"), minus ("-"), or equal sign ("="), Excel interprets this value as a formula. Locale-shaped strings (such as the date "19-8-2025" in nl-NL or fr-FR, format DD-MM-YYYY) are stored as text instead of as dates. To ensure dates are stored as dates, use a locale-aware API like formulasLocal or use a locale-neutral format like ISO (YYYY-MM-DD) or a numeric date serial.

values: any[][];

Property Value

any[][]

Remarks

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-cell-control.yaml

// Change the value of the checkbox in B3.
await Excel.run(async (context) => {
  const sheet = context.workbook.worksheets.getActiveWorksheet();
  const range = sheet.getRange("B3");

  range.values = [["TRUE"]];
  await context.sync();
});

valuesAsJson

A JSON representation of the values in the cells in this range. Unlike Range.values, Range.valuesAsJson supports all data types which can be in a cell. Examples include formatted number values and web images, in addition to the standard Boolean, number, and string values. Data returned from this API always aligns with the en-US locale. To retrieve data in the user's display locale, use Range.valuesAsJsonLocal.

valuesAsJson: CellValue[][];

Property Value

Excel.CellValue[][]

Remarks

API set: ExcelApi 1.16

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/20-data-types/data-types-formatted-number.yaml

// This function creates a double data type,
// and sets the format of this data type as a date.
await Excel.run(async (context) => {
  // Get the Sample worksheet and a range on that sheet.
  const sheet = context.workbook.worksheets.getItemOrNullObject("Sample");
  const dateRange = sheet.getRange("A1");

  // Write a number formatted as a date to cell A1.
  dateRange.valuesAsJson = [
    [
      {
        type: Excel.CellValueType.double,
        basicValue: 32889.0,
        numberFormat: "m/d/yyyy"
      }
    ]
  ];
  await context.sync();
});

valuesAsJsonLocal

A JSON representation of the values in the cells in this range. Unlike Range.values, Range.valuesAsJsonLocal supports all data types which can be in a cell. Examples include formatted number values and web images, in addition to the standard Boolean, number, and string values. Data returned from this API always aligns with the user's display locale. To retrieve data independent of locale, use Range.valuesAsJson.

valuesAsJsonLocal: CellValue[][];

Property Value

Excel.CellValue[][]

Remarks

API set: ExcelApi 1.16

valueTypes

Specifies the type of data in each cell.

readonly valueTypes: Excel.RangeValueType[][];

Property Value

Excel.RangeValueType[][]

Remarks

width

Returns the distance in points, for 100% zoom, from the left edge of the range to the right edge of the range.

readonly width: number;

Property Value

number

Remarks

worksheet

The worksheet containing the current range.

readonly worksheet: Excel.Worksheet;

Property Value

Excel.Worksheet

Remarks