> ## 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.

# Range

## `Range`

A live span of one paragraph's text, in UTF-16 offsets local to it. The
paragraph anchor is an element reference (structural edits cannot rot it);
the offsets are validated against a text snapshot before every edit. When
other edits shift the span, the range follows its snapshot text if it still
occurs exactly once in the paragraph — so a forward search-and-replace loop
works — and throws on any ambiguity instead of landing on the wrong span.

Import from `@reductoai/docx/node`, `@reductoai/docx/officejs`.

### Range properties

| Name | Type | Description |
| - | - | - |
| `bold` | `boolean \| null \| undefined` | |
| `boldBidirectional` | `boolean \| null \| undefined` | |
| `bookmarks` | `HandleCollection<Bookmark>` | read-only office.js Range.bookmarks: the bookmarks the window touches, hidden ones excluded. |
| `borders` | `BorderUniversalCollection` | read-only office.js Range.borders: Top, Left, Bottom, Right, Between over every covered paragraph. |
| `case` | `CharacterCase` | office.js Range.case: Lower, Upper, TitleSentence or TitleWord; Toggle when mixed, Next with no letters. |
| `contentControls` | `ContentControlCollection` | read-only office.js Range.contentControls: every control whose content the window touches. |
| `coversMark` | `boolean` | read-only True when the range runs past its last paragraph's mark, as `paragraph.getRange()` does. |
| `emphasisMark` | `EmphasisMark \| null \| undefined` | |
| `end` | `number` | read-only |
| `endnotes` | `HandleCollection<NoteItem>` | read-only office.js Range.endnotes: the endnotes whose reference mark the window holds. |
| `equations` | `HandleCollection<Equation>` | read-only Extension: the equations inside the window, read and rewritten as TeX. |
| `fields` | `FieldCollection` | read-only office.js Range.fields: read-only, every field whose result the window touches. |
| `font` | `Font` | read-only |
| `footnotes` | `HandleCollection<NoteItem>` | read-only office.js Range.footnotes: the footnotes whose reference mark the window holds. |
| `frames` | `FrameCollection` | read-only office.js Range.frames: the text frames the range's paragraphs belong to. |
| `hasNoProofing` | `boolean \| null` | office.js Range.hasNoProofing: true when every run carries w:noProof, null when mixed. |
| `hyperlink` | `string` | office.js Range.hyperlink: the link's address, "" when unlinked; "" unlinks, keeping the text. |
| `hyperlinks` | `HandleCollection<Hyperlink>` | read-only office.js Range.hyperlinks: the hyperlinks whose text the window touches. |
| `inlinePictures` | `HandleCollection<InlinePicture>` | read-only office.js Range.inlinePictures: the inline pictures positioned inside the window. |
| `isEmpty` | `boolean` | read-only No live text and no struck text: a deletion's range is not empty, as in Word. |
| `italic` | `boolean \| null \| undefined` | |
| `italicBidirectional` | `boolean \| null \| undefined` | |
| `languageId` | `string \| null` | office.js Range.languageId: the Latin proofing language as a Word.LanguageId name ("EnglishUK"), a BCP 47 tag when Word's list has no name for it, "" when unset, null when mixed. |
| `languageIdFarEast` | `string \| null` | office.js Range.languageIdFarEast: the East Asian language (w:lang/@w:eastAsia), "" when unset, null when mixed. |
| `listFormat` | `ListFormat` | read-only office.js Range.listFormat: numbering reads off the FIRST list paragraph, writes on all. |
| `lists` | `HandleCollection<List>` | read-only office.js Range.lists: the lists the window's paragraphs belong to, once each. |
| `paragraph` | `Paragraph` | read-only The paragraph this range lives in — the hop from a search hit to block-level edits. |
| `paragraphs` | `ParagraphCollection<Paragraph>` | read-only Every paragraph the range touches: one, or the whole span an expandTo built. |
| `parentBody` | `Body` | read-only |
| `parentContentControl` | `ContentControl` | read-only |
| `parentContentControlOrNullObject` | `ContentControl` | read-only |
| `parentField` | `Field \| undefined` | read-only The field whose cached RESULT this range sits in, undefined for real text. A search hit inside a REF's result is DERIVED ink the next updateFields rewrites; this is the one read that tells the two apart. |
| `parentTable` | `Table` | read-only |
| `parentTableCell` | `TableCell` | read-only |
| `parentTableCellOrNullObject` | `TableCell & { isNullObject: boolean }` | read-only |
| `parentTableOrNullObject` | `Table & { isNullObject: boolean }` | read-only |
| `revisions` | `RevisionCollection` | read-only |
| `sections` | `SectionCollection<Section>` | read-only office.js Range.sections: the sections the window's paragraphs belong to, once each. |
| `shading` | `ParagraphShadingUniversal` | read-only office.js Range.shading: `w:pPr/w:shd` over every covered paragraph. |
| `shapes` | `HandleCollection<Shape>` | read-only office.js Range.shapes: the floating shapes anchored inside the window. |
| `start` | `number` | read-only |
| `storyLength` | `number` | read-only |
| `storyType` | `"MainText"` | read-only |
| `style` | `string \| undefined` | Word dispatches a style assignment on the style's `w:type`: a character style becomes `w:rStyle` on the runs in scope, anything else becomes the paragraphs' `w:pStyle`. Reads mirror that — the character style when the whole scope carries one, the paragraph style otherwise. |
| `styleBuiltIn` | `string \| undefined` | |
| `tableColumns` | `HandleCollection<TableColumn>` | read-only office.js Range.tableColumns: each touched table's columns, in grid order. |
| `tables` | `TableCollection<Table>` | read-only office.js Range.tables: every table the window touches, once, in document order. |
| `text` | `string` | read-only Word's text: paragraphs end in "\r", and a range that holds a paragraph's mark ends in one too. |

### `Range.clear()`

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

### `Range.compareLocationWith()`

```ts theme={null}
compareLocationWith(range: Range): ClientResult<LocationRelation>
```

office.js Range.compareLocationWith: where this range sits relative to
another in document order. Ranges of two stories read Unrelated.

### `Range.convertToTable()`

```ts theme={null}
convertToTable(options?: ConvertToTableOptions): Table
```

Extension (VBA Range.ConvertToTable): each paragraph of the range becomes a row, split into
cells at the separator (Tabs by default). The range's handle is spent; use the returned Table.

### `Range.delete()`

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

Remove the range; one that holds a paragraph mark takes the mark (and so the paragraph) too.

### `Range.expandTo()`

```ts theme={null}
expandTo(range: Range): Range
```

office.js Range.expandTo: the span from the earlier start to the later end
of two ranges in document order. Both must live in the SAME story.

### `Range.expandToOrNullObject()`

```ts theme={null}
expandToOrNullObject(range: Range): Range & { isNullObject: boolean }
```

expandTo, with the null object instead of the cross-story/detached refusals.

### `Range.getBookmarks()`

```ts theme={null}
getBookmarks(includeHidden?: boolean, includeAdjacent?: boolean): ClientResult<string[]>
```

Names of the bookmarks covering this range, in document order.

### `Range.getComments()`

```ts theme={null}
getComments(): CommentCollection
```

### `Range.getContentControls()`

```ts theme={null}
getContentControls(options?: ContentControlOptions): ContentControlCollection
```

### `Range.getHtml()`

```ts theme={null}
getHtml(): ClientResult<string>
```

As Word: tables as `<table>`, `<h1>-<h6>` for headings, list markers as text, b/i/u/s/sup/sub
and links inline. A paragraph whose mark is outside the range is written inline.

### `Range.getHyperlink()`

```ts theme={null}
getHyperlink(): string | undefined
```

The address of the hyperlink containing this range, if any: the target URL
for an external link (`r:id`), `"#Bookmark"` for an internal one
(`w:anchor`). (OfficeJS `range.hyperlink` is one read/write property;
explicit verbs keep "link this text" apart from "replace this text".)

### `Range.getHyperlinkRanges()`

```ts theme={null}
getHyperlinkRanges(): RangeCollection<Range>
```

office.js Range.getHyperlinkRanges: the hyperlink child ranges inside this range.

### `Range.getHyperlinkTooltip()`

```ts theme={null}
getHyperlinkTooltip(): string | undefined
```

The ScreenTip (`w:tooltip`) of the hyperlink containing this range: the
read half of setHyperlink's second argument, `undefined` when the range is
unlinked or the link carries none. OfficeJS has no tooltip member at all.

### `Range.getNextTextRange()`

```ts theme={null}
getNextTextRange(endingMarks: string[], trimSpacing?: boolean): Range
```

office.js Range.getNextTextRange: the next segment of the story, or ItemNotFound.

### `Range.getNextTextRangeOrNullObject()`

```ts theme={null}
getNextTextRangeOrNullObject(
  endingMarks: string[],
  trimSpacing?: boolean,
): Range & { isNullObject: boolean }
```

getNextTextRange, with the null object instead of every refusal it makes.

### `Range.getOoxml()`

```ts theme={null}
getOoxml(): ClientResult<string>
```

The range's own WML, a text-only HTML span, and the reviewed-text projection.

### `Range.getRange()`

```ts theme={null}
getRange(location?: RangeLocation): Range
```

### `Range.getReviewedText()`

```ts theme={null}
getReviewedText(version?: "Original" | "Current"): ClientResult<string>
```

### `Range.getTextRanges()`

```ts theme={null}
getTextRanges(endingMarks: string[], trimSpacing?: boolean): RangeCollection<Range>
```

### `Range.getTrackedChanges()`

```ts theme={null}
getTrackedChanges(): TrackedChangeCollection
```

### `Range.highlight()`

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

### `Range.insertBookmark()`

```ts theme={null}
insertBookmark(name: string): void
```

Bookmark this range; re-using a name moves that bookmark here, as Word does.

### `Range.insertBreak()`

```ts theme={null}
insertBreak(breakType: BreakType, insertLocation?: BlockInsertLocation): void
```

Insert a break before or after this range's start/end paragraph.

### `Range.insertCanvas()`

```ts theme={null}
insertCanvas(insertShapeOptions?: InsertShapeOptions): Shape
```

Insert an empty floating canvas anchored to this range's paragraph; geometry in points.

### `Range.insertCaption()`

```ts theme={null}
insertCaption(label: string, options?: InsertCaptionOptions): Paragraph
```

VBA Range.InsertCaption: a Caption paragraph numbered by SEQ `label`, below (default) or above
the body block that holds this range; later captions of the label renumber.

### `Range.insertComment()`

```ts theme={null}
insertComment(commentText: string): Comment
```

A spanning range opens the comment in its first paragraph and closes it in its last, as Word does.

### `Range.insertContentControl()`

```ts theme={null}
insertContentControl(type?: ContentControlType): ContentControl
```

Wrap this range in a content control: a block-level w:sdt around the blocks
of a paragraph-aligned range (one paragraph or many), an inline w:sdt
around the runs of a partial one-paragraph range.

### `Range.insertCrossReference()`

```ts theme={null}
insertCrossReference(
  referenceType: string,
  referenceKind: ReferenceKind,
  referenceItem: string | number,
  options?: InsertCrossReferenceOptions & { insertLocation?: FieldInsertLocation },
): Field
```

VBA Range.InsertCrossReference: a REF, PAGEREF or NOTEREF field to the `referenceItem`th entry of
Document.getCrossReferenceItems(referenceType), or the entry with that text. A heading,
numbered item, note or caption gets Word's hidden \_Ref bookmark, reused when one is there.

### `Range.insertEndnote()`

```ts theme={null}
insertEndnote(insertText?: string): NoteItem
```

Insert an endnote mark at this range's end; the note body starts with `insertText`.

### `Range.insertField()`

```ts theme={null}
insertField(
  insertLocation: FieldInsertLocation,
  fieldType?: string,
  text?: string,
  removeFormatting?: boolean,
): Field
```

Author a field at one of Word's five anchor points; `text` carries its switches.

### `Range.insertFileFromBase64()`

```ts theme={null}
insertFileFromBase64(
  base64File: DocxFile,
  insertLocation?: PictureInsertLocation,
): Promise<Range>
```

A .docx's body at insertOoxml's anchors, with its parts; async, the file is unpacked here.

### `Range.insertFootnote()`

```ts theme={null}
insertFootnote(insertText?: string): NoteItem
```

Insert a footnote mark at this range's end; the note body starts with `insertText`.

### `Range.insertGeometricShape()`

```ts theme={null}
insertGeometricShape(
  geometricShapeType: GeometricShapeType,
  insertShapeOptions?: InsertShapeOptions,
): Shape
```

Insert a floating preset shape anchored to this range's paragraph; geometry in points.

### `Range.insertHtml()`

```ts theme={null}
insertHtml(html: string, insertLocation?: PictureInsertLocation): Range
```

The named HTML subset at those same anchors; any other tag throws by name.

### `Range.insertInlinePictureFromBase64()`

```ts theme={null}
insertInlinePictureFromBase64(
  base64: string,
  insertLocation?: PictureInsertLocation,
): InlinePicture
```

Insert a PNG, JPEG, GIF, BMP, TIFF, EMF or WMF at its natural size, anchored to one of the range's five edges.

### `Range.insertMath()`

```ts theme={null}
insertMath(...__namedParameters: InsertMathArgs<PictureInsertLocation>): Range
```

Extension: TeX math as a native Office Math equation, at insertOoxml's anchors.

### `Range.insertOoxml()`

```ts theme={null}
insertOoxml(ooxml: string, insertLocation?: PictureInsertLocation): Range
```

A WML fragment or `pkg:package` payload at any of the range's five anchors.

### `Range.insertParagraph()`

```ts theme={null}
insertParagraph(text: string, location?: "Before" | "After"): Paragraph
```

### `Range.insertScene()`

```ts theme={null}
insertScene(options: SceneOptions): Shape
```

Insert one floating group of preset shapes and connectors anchored to this range's paragraph.

### `Range.insertSymbol()`

```ts theme={null}
insertSymbol(characterNumber: number, font: string, at?: InsertLocation): Range
```

Extension: VBA's Range.InsertSymbol; a U+F000–U+F0FF code is a w:sym, any other text in `font`.

### `Range.insertTable()`

```ts theme={null}
insertTable(
  rowCount: number,
  columnCount: number,
  insertLocation?: BlockInsertLocation,
  values?: string[][],
): Table
```

Insert a table before or after this range's start/end paragraph.

### `Range.insertText()`

```ts theme={null}
insertText(
  text: string,
  location?: InsertLocation,
  format?: OfficeRunFormatInput,
): Range
```

The inserted text's range (first line); a newline splits only where no text crosses the split.

### `Range.insertTextBox()`

```ts theme={null}
insertTextBox(text?: string, insertShapeOptions?: TextBoxOptions): Shape
```

Insert a floating textbox anchored to this range's paragraph; geometry in points.

### `Range.intersectWith()`

```ts theme={null}
intersectWith(range: Range): Range
```

office.js Range.intersectWith: the span the two ranges share, same story only.

### `Range.intersectWithOrNullObject()`

```ts theme={null}
intersectWithOrNullObject(range: Range): Range & { isNullObject: boolean }
```

intersectWith, with the null object instead of every refusal it makes.

### `Range.removeHighlight()`

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

### `Range.search()`

```ts theme={null}
search(needle: string, options?: SearchOptions): RangeCollection<Range>
```

Literal hits of `needle` inside this range.

### `Range.set()`

```ts theme={null}
set(properties: RangeUpdateData, options?: UpdateOptions): void
```

### `Range.setHyperlink()`

```ts theme={null}
setHyperlink(url: string, tooltip?: string | null): void
```

Link this range's text; see setRangeHyperlink for the whole contract.

### `Range.sort()`

```ts theme={null}
sort(options?: ParagraphSortOptions): void
```

Extension (VBA Range.Sort on text): the range's paragraphs reorder by their text, ties stable.
excludeHeader keeps the first paragraph in place. Sort a table with Table.sort.

### `Range.split()`

```ts theme={null}
split(
  delimiters: string[],
  multiParagraphs?: boolean,
  trimDelimiters?: boolean,
  trimSpacing?: boolean,
): RangeCollection<Range>
```

office.js Range.split: getTextRanges over delimiters, with the two extra knobs.

**Not implemented.** These Office.js members throw: `characterWidth`, `combineCharacters`, `conflicts`, `disableCharacterSpaceGrid`, `editors`, `fitTextWidth`, `grammarChecked`, `highlightColorIndex`, `horizontalInVertical`, `id`, `isEndOfRowMark`, `isTextVisibleOnScreen`, `kana`, `languageDetected`, `languageIdOther`, `pages`, `showAll`, `spellingChecked`, `twoLinesInOne`, `detectLanguage`, `insertPictureFromBase64`, `select`.

## `RangeCollection`

OfficeJS-flavored live collection: `items` is recomputed on every access.

Import from `@reductoai/docx/node`, `@reductoai/docx/officejs`.

### RangeCollection properties

| Name | Type | Description |
| - | - | - |
| `items` | `T[]` | read-only |
| `length` | `number` | read-only |

### `RangeCollection.at()`

```ts theme={null}
at(index: number): T
```

### `RangeCollection.getFirst()`

```ts theme={null}
getFirst(): T
```

### `RangeCollection.getFirstOrNullObject()`

```ts theme={null}
getFirstOrNullObject(): T & { isNullObject: boolean }
```

OfficeJS null-object variant; inspect `isNullObject` before other members.

### `RangeCollection.getItem()`

```ts theme={null}
getItem(index: number): T
```

OfficeJS spelling of at().

### `RangeCollection.getLast()`

```ts theme={null}
getLast(): T
```

### `RangeCollection.getLastOrNullObject()`

```ts theme={null}
getLastOrNullObject(): T & { isNullObject: boolean }
```

OfficeJS null-object variant; inspect `isNullObject` before other members.

## `SearchOptions`

OfficeJS SearchOptions shape. Literal search supports case, whole-word,
prefix/suffix matching; matchWildcards switches to Word's wildcard syntax
(case-sensitive, the other switches ignored as Word greys them out);
ignorePunct/ignoreSpace let the text hold punctuation/spaces the needle lacks.

Import from `@reductoai/docx/node`, `@reductoai/docx/officejs`.

| Name | Type | Description |
| - | - | - |
| `ignorePunct?` | `boolean` | |
| `ignoreSpace?` | `boolean` | |
| `matchCase?` | `boolean` | |
| `matchPrefix?` | `boolean` | |
| `matchSuffix?` | `boolean` | |
| `matchWholeWord?` | `boolean` | |
| `matchWildcards?` | `boolean` | |
