> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reducto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# ExcelRange

## `ExcelRange`

`Excel.Range`: a fixed rectangle of one sheet. Reads are current; writes apply at once.

Import from `@reductoai/xlsx/officejs`.

### ExcelRange properties

| Name | Type | Description |
| - | - | - |
| `address` | `string` | read-only |
| `addressLocal` | `string` | read-only |
| `cellCount` | `number` | read-only |
| `columnCount` | `number` | read-only |
| `columnHidden` | `boolean \| null` | True when every column is hidden, false when none is, null when some are. |
| `columnIndex` | `number` | read-only |
| `conditionalFormats` | `ConditionalFormatCollection` | read-only |
| `control` | `CellControl` | |
| `dataValidation` | `DataValidation` | read-only |
| `format` | `RangeFormat` | read-only |
| `formulaArray` | `string \| null` | The legacy array formula all cells sit in; null when they do not share one. |
| `formulas` | `(string \| number \| boolean)[][]` | A cell a spill fills reads as "", as in Excel, whether computed here or loaded. |
| `formulasLocal` | `(string \| number \| boolean)[][]` | The formulas in the en-US form this facade reads and writes. |
| `formulasR1C1` | `(string \| number \| boolean)[][]` | Each formula in R1C1 notation, relative to its own cell. |
| `hasSpill` | `boolean \| null` | read-only True when every cell sits in a spill, false when none does, null when some do. |
| `height` | `number` | read-only Points; hidden rows count as 0. |
| `hidden` | `boolean` | read-only True when every row or every column of the range is hidden. |
| `hyperlink` | `RangeHyperlink \| null` | The hyperlink of the top-left cell; null when it has none. |
| `isEntireColumn` | `boolean` | read-only |
| `isEntireRow` | `boolean` | read-only |
| `left` | `number` | read-only Points from column A's left edge to the range's left edge. |
| `numberFormat` | `string[][]` | |
| `numberFormatCategories` | `NumberFormatCategory[][]` | read-only |
| `numberFormatLocal` | `string[][]` | The number formats in the en-US form this facade reads and writes. |
| `rect` | `Readonly<Rect>` | read-only Extension: the rectangle, zero-based and inclusive. |
| `rowCount` | `number` | read-only |
| `rowHidden` | `boolean \| null` | True when every row is hidden, false when none is, null when some are. |
| `rowIndex` | `number` | read-only |
| `savedAsArray` | `boolean \| null` | read-only True when every cell is in an array formula's area or anchors a dynamic one. |
| `sort` | `RangeSort` | read-only |
| `style` | `string \| null` | The cell style the cells are based on; null when they differ. |
| `text` | `string[][]` | read-only |
| `top` | `number` | read-only Points from row 1's top edge to the range's top edge. |
| `values` | `(string \| number \| boolean)[][]` | |
| `valuesAsJson` | `BasicCellValue[][]` | Each cell's value as an Office.js `CellValue`. |
| `valuesAsJsonLocal` | `BasicCellValue[][]` | |
| `valueTypes` | `RangeValueType[][]` | read-only |
| `width` | `number` | read-only Points; hidden columns count as 0. |
| `worksheet` | `ExcelWorksheet` | read-only |

### `ExcelRange.advancedFilter()`

```ts theme={null}
advancedFilter(
  action: FilterAction,
  criteriaRange?: string | ExcelRange | null,
  copyToRange?: string | ExcelRange | null,
  unique?: boolean,
): number
```

Extension (VBA's `Range.AdvancedFilter`): filters this list in place by a criteria range, or copies
the records under the header row of `copyToRange`. Returns the number of records shown or copied.

### `ExcelRange.autoFill()`

```ts theme={null}
autoFill(destinationRange: string | ExcelRange, autoFillType?: AutoFillType): void
```

Fills `destinationRange`, which holds this range and grows it along one side, as dragging the fill handle does.

### `ExcelRange.calculate()`

```ts theme={null}
calculate(): void
```

### `ExcelRange.clear()`

```ts theme={null}
clear(applyTo?: ClearApplyTo): void
```

### `ExcelRange.clearOrResetContents()`

```ts theme={null}
clearOrResetContents(): void
```

Clears the values and formulas; this facade has no cell controls to reset.

### `ExcelRange.consolidate()`

```ts theme={null}
consolidate(
  sources: (string | ExcelRange)[],
  fn?: ConsolidationFunction,
  topRow?: boolean,
  leftColumn?: boolean,
): ExcelRange
```

Extension (VBA's `Range.Consolidate`): one block summarizing the sources by place or by their labels, from this range's top-left cell; gives the block.

### `ExcelRange.copyFrom()`

```ts theme={null}
copyFrom(
  sourceRange: string | ExcelRange | RangeAreas,
  copyType?: RangeCopyType,
  skipBlanks?: boolean,
  transpose?: boolean,
): void
```

Pastes `sourceRange` here as Excel's copy and paste (special) does; tiles when this range holds it a whole number of times.

### `ExcelRange.delete()`

```ts theme={null}
delete(shift: DeleteShiftDirection): void
```

Deletes the cells and closes the gap from below (`Up`) or the right (`Left`); whole rows or columns go entirely.

### `ExcelRange.find()`

```ts theme={null}
find(text: string, criteria?: SearchCriteria): ExcelRange
```

The first cell whose formula or constant matches; from one cell, the next match on the sheet.

### `ExcelRange.findOrNullObject()`

```ts theme={null}
findOrNullObject(text: string, criteria?: SearchCriteria): Nullable<ExcelRange>
```

### `ExcelRange.getAbsoluteResizedRange()`

```ts theme={null}
getAbsoluteResizedRange(numRows: number, numColumns: number): ExcelRange
```

### `ExcelRange.getBoundingRect()`

```ts theme={null}
getBoundingRect(anotherRange: string | ExcelRange): ExcelRange
```

### `ExcelRange.getCell()`

```ts theme={null}
getCell(row: number, column: number): ExcelRange
```

### `ExcelRange.getCellProperties()`

```ts theme={null}
getCellProperties(
  options: PropertyLoadOptions,
): ClientResult<Record<string, unknown>[][]>
```

Each cell's members that `options` asks for; `true` on a branch loads all of it.

### `ExcelRange.getColumn()`

```ts theme={null}
getColumn(column: number): ExcelRange
```

### `ExcelRange.getColumnProperties()`

```ts theme={null}
getColumnProperties(
  options: PropertyLoadOptions,
): ClientResult<Record<string, unknown>[]>
```

One entry per column of the range, read down the range's rows.

### `ExcelRange.getColumnsAfter()`

```ts theme={null}
getColumnsAfter(count?: number): ExcelRange
```

### `ExcelRange.getColumnsBefore()`

```ts theme={null}
getColumnsBefore(count?: number): ExcelRange
```

### `ExcelRange.getDependents()`

```ts theme={null}
getDependents(): WorkbookRangeAreas
```

### `ExcelRange.getDirectDependents()`

```ts theme={null}
getDirectDependents(): WorkbookRangeAreas
```

### `ExcelRange.getDirectPrecedents()`

```ts theme={null}
getDirectPrecedents(): WorkbookRangeAreas
```

The cells of a kind, as Excel's Go To Special finds them; throws when there are none.

### `ExcelRange.getDisplayedCellProperties()`

```ts theme={null}
getDisplayedCellProperties(
  options: PropertyLoadOptions,
): ClientResult<Record<string, unknown>[][]>
```

As `getCellProperties`, with fonts, fills and borders as conditional formats show them.

### `ExcelRange.getEntireColumn()`

```ts theme={null}
getEntireColumn(): ExcelRange
```

### `ExcelRange.getEntireRow()`

```ts theme={null}
getEntireRow(): ExcelRange
```

### `ExcelRange.getExtendedRange()`

```ts theme={null}
getExtendedRange(
  direction: KeyboardDirection,
  activeCell?: string | ExcelRange,
): ExcelRange
```

The range Ctrl+Shift+Arrow selects from this one.

### `ExcelRange.getImage()`

```ts theme={null}
getImage(options?: GetImageOptions): Promise<string>
```

A Base64 PNG of the cells as Office.js paints them: no headers, and gridlines only when the
sheet shows them; at most 1,000 rows by 100 columns from the top-left cell. A promise, not a ClientResult.
Extension: `{ labels: true }` adds column letters and row numbers, so a model can name the
cell under a mark. In a browser, import `@reductoai/xlsx/view` once; `@reductoai/xlsx/node`
brings its own painter.

### `ExcelRange.getIntersection()`

```ts theme={null}
getIntersection(anotherRange: string | ExcelRange): ExcelRange
```

### `ExcelRange.getIntersectionOrNullObject()`

```ts theme={null}
getIntersectionOrNullObject(
  anotherRange: string | ExcelRange,
): ExcelRange & { isNullObject: boolean }
```

### `ExcelRange.getLastCell()`

```ts theme={null}
getLastCell(): ExcelRange
```

### `ExcelRange.getLastColumn()`

```ts theme={null}
getLastColumn(): ExcelRange
```

### `ExcelRange.getLastRow()`

```ts theme={null}
getLastRow(): ExcelRange
```

### `ExcelRange.getMergedAreasOrNullObject()`

```ts theme={null}
getMergedAreasOrNullObject(): Nullable<RangeAreas>
```

The merged areas that overlap this range.

### `ExcelRange.getOffsetRange()`

```ts theme={null}
getOffsetRange(rowOffset: number, columnOffset: number): ExcelRange
```

### `ExcelRange.getPivotTables()`

```ts theme={null}
getPivotTables(fullyContained?: boolean): PivotTableScopedCollection
```

Pivot tables that overlap the range, or lie inside it with `fullyContained`.

### `ExcelRange.getPrecedents()`

```ts theme={null}
getPrecedents(): WorkbookRangeAreas
```

### `ExcelRange.getRangeEdge()`

```ts theme={null}
getRangeEdge(direction: KeyboardDirection, activeCell?: string | ExcelRange): ExcelRange
```

The cell Ctrl+Arrow lands on from the active cell (the top-left by default).

### `ExcelRange.getResizedRange()`

```ts theme={null}
getResizedRange(deltaRows: number, deltaColumns: number): ExcelRange
```

### `ExcelRange.getRow()`

```ts theme={null}
getRow(row: number): ExcelRange
```

### `ExcelRange.getRowProperties()`

```ts theme={null}
getRowProperties(options: PropertyLoadOptions): ClientResult<Record<string, unknown>[]>
```

One entry per row of the range, read across the range's columns.

### `ExcelRange.getRowsAbove()`

```ts theme={null}
getRowsAbove(count?: number): ExcelRange
```

### `ExcelRange.getRowsBelow()`

```ts theme={null}
getRowsBelow(count?: number): ExcelRange
```

### `ExcelRange.getSpecialCells()`

```ts theme={null}
getSpecialCells(
  cellType: SpecialCellType,
  cellValueType?: SpecialCellValueType,
): RangeAreas
```

### `ExcelRange.getSpecialCellsOrNullObject()`

```ts theme={null}
getSpecialCellsOrNullObject(
  cellType: SpecialCellType,
  cellValueType?: SpecialCellValueType,
): RangeAreas & { isNullObject: boolean }
```

### `ExcelRange.getSpillingToRange()`

```ts theme={null}
getSpillingToRange(): ExcelRange
```

### `ExcelRange.getSpillingToRangeOrNullObject()`

```ts theme={null}
getSpillingToRangeOrNullObject(): ExcelRange & { isNullObject: boolean }
```

### `ExcelRange.getSpillParent()`

```ts theme={null}
getSpillParent(): ExcelRange
```

### `ExcelRange.getSpillParentOrNullObject()`

```ts theme={null}
getSpillParentOrNullObject(): ExcelRange & { isNullObject: boolean }
```

### `ExcelRange.getSurroundingRegion()`

```ts theme={null}
getSurroundingRegion(): ExcelRange
```

Excel's current region around the top-left cell: bounded by blank rows and columns.

### `ExcelRange.getTables()`

```ts theme={null}
getTables(fullyContained?: boolean): TableScopedCollection
```

The tables that overlap this range, or only those inside it.

### `ExcelRange.getUsedRange()`

```ts theme={null}
getUsedRange(valuesOnly?: boolean): ExcelRange
```

### `ExcelRange.getUsedRangeOrNullObject()`

```ts theme={null}
getUsedRangeOrNullObject(valuesOnly?: boolean): ExcelRange & { isNullObject: boolean }
```

### `ExcelRange.getVisibleView()`

```ts theme={null}
getVisibleView(): RangeView
```

The cells that hidden rows and columns leave showing.

### `ExcelRange.group()`

```ts theme={null}
group(groupOption: GroupOption): void
```

Adds one outline level to the rows or columns of the range; seven is the most.

### `ExcelRange.hideGroupDetails()`

```ts theme={null}
hideGroupDetails(groupOption: GroupOption): void
```

Collapses the group a summary row or column heads, else the innermost group holding the range.

### `ExcelRange.insert()`

```ts theme={null}
insert(shift: InsertShiftDirection): ExcelRange
```

Inserts cells the size of this range and returns them. Whole rows or columns insert rows
or columns; otherwise `shift` pushes the cells below (`Down`) or to the right (`Right`).
References, merges, formats and anchors follow the moved cells as in Excel.

### `ExcelRange.merge()`

```ts theme={null}
merge(across?: boolean): void
```

Merges the range, or each of its rows with `across`; only the top-left value is kept.

### `ExcelRange.moveTo()`

```ts theme={null}
moveTo(destinationRange: string | ExcelRange): void
```

Cuts the range and pastes it with its top-left cell at `destinationRange`'s, as Excel's cut and paste does.

### `ExcelRange.removeDuplicates()`

```ts theme={null}
removeDuplicates(columns: number[], includesHeader: boolean): RemoveDuplicatesResult
```

Keeps the first row of each key; keys compare shown text, ignoring case.

### `ExcelRange.replaceAll()`

```ts theme={null}
replaceAll(
  text: string,
  replacement: string,
  criteria?: ReplaceCriteria,
): ClientResult<number>
```

Replaces in formulas and constants as Excel's Replace All does; each changed cell is entered again.

### `ExcelRange.select()`

```ts theme={null}
select(): void
```

Office.js `select` moves the UI selection; a file has none to move.

### `ExcelRange.set()`

```ts theme={null}
set(properties: ExcelRange | UpdateData<ExcelRange>, options?: UpdateOptions): void
```

Sets several properties at once; a navigation member takes a nested batch.

### `ExcelRange.setCellProperties()`

```ts theme={null}
setCellProperties(values: Record<string, unknown>[][]): void
```

Writes each cell's members; the grid must be the range's size.

### `ExcelRange.setColumnProperties()`

```ts theme={null}
setColumnProperties(values: Record<string, unknown>[]): void
```

### `ExcelRange.setDirty()`

```ts theme={null}
setDirty(): void
```

Marks the cells to calculate again at the next recalculation.

### `ExcelRange.setRowProperties()`

```ts theme={null}
setRowProperties(values: Record<string, unknown>[]): void
```

### `ExcelRange.showGroupDetails()`

```ts theme={null}
showGroupDetails(groupOption: GroupOption): void
```

Expands that group; groups inside it that are collapsed stay so.

### `ExcelRange.ungroup()`

```ts theme={null}
ungroup(groupOption: GroupOption): void
```

Removes one outline level; throws when no row or column of the range has one.

### `ExcelRange.unmerge()`

```ts theme={null}
unmerge(): void
```

Blank cells a merge left with no format of their own go, as in Excel.

## `RangeValueType`

Import from `@reductoai/xlsx/officejs`.

```ts theme={null}
type RangeValueType = "Empty" | "String" | "Double" | "Boolean" | "Error"
```

## `RangeAreas`

`Excel.RangeAreas`: rectangles of one sheet, kept in the order given.

Import from `@reductoai/xlsx/officejs`.

### RangeAreas properties

| Name | Type | Description |
| - | - | - |
| `address` | `string` | read-only |
| `addressLocal` | `string` | read-only |
| `areaCount` | `number` | read-only |
| `areas` | `RangeCollection` | read-only |
| `cellCount` | `number` | read-only The sum over the areas; -1 past 2^31 - 1, as Excel reports. |
| `conditionalFormats` | `ConditionalFormatCollection` | read-only |
| `dataValidation` | `DataValidation` | read-only |
| `format` | `RangeFormat` | read-only Writes reach every area; a read is null when the areas differ. |
| `isEntireColumn` | `boolean` | read-only |
| `isEntireRow` | `boolean` | read-only |
| `rects` | `readonly Readonly<Rect>[]` | read-only Extension: the rectangles, zero-based and inclusive. |
| `style` | `string \| null` | The style every area shares, or null when they differ. |
| `worksheet` | `ExcelWorksheet` | read-only |

### `RangeAreas.calculate()`

```ts theme={null}
calculate(): void
```

### `RangeAreas.clear()`

```ts theme={null}
clear(applyTo?: ClearApplyTo): void
```

### `RangeAreas.clearOrResetContents()`

```ts theme={null}
clearOrResetContents(): void
```

### `RangeAreas.copyFrom()`

```ts theme={null}
copyFrom(
  sourceRange: string | ExcelRange | RangeAreas,
  copyType?: RangeCopyType,
  skipBlanks?: boolean,
  transpose?: boolean,
): void
```

Pastes the source at the top-left of each area.

### `RangeAreas.getEntireColumn()`

```ts theme={null}
getEntireColumn(): RangeAreas
```

### `RangeAreas.getEntireRow()`

```ts theme={null}
getEntireRow(): RangeAreas
```

### `RangeAreas.getIntersection()`

```ts theme={null}
getIntersection(anotherRange: string | ExcelRange | RangeAreas): RangeAreas
```

### `RangeAreas.getIntersectionOrNullObject()`

```ts theme={null}
getIntersectionOrNullObject(anotherRange: string | ExcelRange | RangeAreas): Areas
```

### `RangeAreas.getOffsetRangeAreas()`

```ts theme={null}
getOffsetRangeAreas(rowOffset: number, columnOffset: number): RangeAreas
```

### `RangeAreas.getSpecialCells()`

```ts theme={null}
getSpecialCells(
  cellType: SpecialCellType,
  cellValueType?: SpecialCellValueType,
): RangeAreas
```

### `RangeAreas.getSpecialCellsOrNullObject()`

```ts theme={null}
getSpecialCellsOrNullObject(
  cellType: SpecialCellType,
  cellValueType?: SpecialCellValueType,
): Areas
```

### `RangeAreas.getTables()`

```ts theme={null}
getTables(fullyContained?: boolean): TableScopedCollection
```

The tables that meet an area, or only those inside one.

### `RangeAreas.getUsedRangeAreas()`

```ts theme={null}
getUsedRangeAreas(valuesOnly?: boolean): RangeAreas
```

Each area clipped to the sheet's used range; areas outside it drop out.

### `RangeAreas.getUsedRangeAreasOrNullObject()`

```ts theme={null}
getUsedRangeAreasOrNullObject(valuesOnly?: boolean): Areas
```

### `RangeAreas.select()`

```ts theme={null}
select(): void
```

### `RangeAreas.set()`

```ts theme={null}
set(properties: RangeAreas | UpdateData<RangeAreas>, options?: UpdateOptions): void
```

Sets several properties at once; a navigation member takes a nested batch.

### `RangeAreas.setDirty()`

```ts theme={null}
setDirty(): void
```

## `RangeSort`

`Excel.RangeSort`.

Import from `@reductoai/xlsx/officejs`.

### `RangeSort.apply()`

```ts theme={null}
apply(
  fields: SortField[],
  matchCase?: boolean,
  hasHeaders?: boolean,
  orientation?: SortOrientation,
  method?: SortMethod,
): void
```

Sorts the range's shown rows (columns with `orientation` "Columns") by `fields`, the first
outermost. A header row (column) stays on top; formulas move as a copy would.

## `parseAddress()`

```ts theme={null}
function parseAddress(text: string): Address | undefined
```

"A1", "A1:B2", "A:C", "2:5" or any of those after `Sheet!`; undefined when it is not an A1 address.

Import from `@reductoai/xlsx/officejs`.

## `formatAddress()`

```ts theme={null}
function formatAddress(sheet: string, r: Rect): string
```

Import from `@reductoai/xlsx/officejs`.
