Word.Range

Word.Range is an object type of the Word module (Office.word(iframe)). 50 methods.

Generated from the SDK type definitions

Word · 14 object types · 259 methods · namespace Word. This reference is generated from the API document artifact (sdk-api-doc.html) produced with the SDK build. Descriptions are the editor's API comments as published. Pin the SDK and Office versions together and regenerate when either changes.

Remarks

• Module: Word · Office.word(iframe) · namespace Word
• Obtained from: Document.getRange(options), Document.getSelection(), Body.getRange(range), Body.insertHtml(html, options), Body.insertText(text, options), Body.search(query, options), Paragraph.getRange(startOffset, endOffset), Paragraph.insertText(text, options), Shape.getRange(), Image.getRange(), Bookmark.getRange(), Hyperlink.getRange()
• Every method returns a Promise; signatures use TypeScript notation.

Methods

Method	Description
acceptChangeTrackings()	Accepts all change-tracking entries overlapping this range.
clearFormat()	Resets the text formatting and paragraph formatting of the range.
clearList()	Removes list formatting from the paragraphs spanned by the range.
copyFormatTo(targetRange)	Copies the style and formatting (text + paragraph) at the start position of this range to the target range.
delete()	Deletes the text of the range.
getBookmarks()	Returns the list of bookmarks whose markers lie within the range.
getChangeTrackings()	Returns the list of change-tracking entries overlapping this range, in document order.
getComments()	Returns the list of comments overlapping this range.
getContentHtml()	Returns the paragraph content spanned by this range as HTML with formatting.
getEndnotes()	Returns the list of endnotes within this range.
getFootnotes()	Returns the list of footnotes within this range.
getFormat()	Returns the text formatting and paragraph formatting at the start position of this range.
getHyperlink()	Returns the hyperlink attached to this range.
getHyperlinks()	Returns the list of text hyperlinks overlapping this range.
getLocation()	Returns the start/end positions of this range as paragraph coordinates.
getNotes()	Returns the list of footnotes and endnotes within this range.
getParagraph()	Returns the start paragraph of this range.
getParentSection()	Returns the section containing the start position of this range.
getShapes()	Returns the list of shapes, images, and charts within this range.
getStructure()	Returns the paragraph/table structure spanned by this range.
getText()	Returns the text contained in this range.
insertBookmark(name)	Inserts a bookmark at the start position of this range.
insertColumnBreak()	Inserts a column break at this range position.
insertComment(text, options)	Inserts a comment on this range.
insertEndnote(text)	Inserts an endnote at the end of this range.
insertFootnote(text)	Inserts a footnote at the end of this range.
insertHyperlink(url, options)	Attaches a hyperlink to this range.
insertImage(options)	Inserts an image inline at the start position of this range.
insertLineBreak()	Inserts a line break at the start position of this range.
insertPageBreak()	Inserts a page break at this range position.
insertParagraph(text, options)	Inserts a new paragraph above or below the anchor paragraph of this range.
insertSectionBreak(type)	Inserts a section break at this range position to create a new section.
insertShape(preset, options)	Inserts a shape of the given preset into the paragraph of this range.
insertSymbol(charCode, options)	Inserts a symbol at the start position of this range.
insertTab()	Inserts a tab character at the start position of this range.
insertTable(rows, columns, options)	Inserts a table relative to the paragraph of the range.
insertText(text, options)	Inserts text into this range.
insertTextbox(options)	Inserts a text box into the paragraph of the range.
insertWebVideo(url, options)	Inserts a web video inline at the start position of this range.
isCollapsed()	Checks whether this range is empty, with the same start and end.
rejectChangeTrackings()	Rejects all change-tracking entries overlapping this range.
search(query, options)	Finds text or special characters (page break/column break/line break/tab/symbol) within this range and returns editable ranges.
select(mode)	Sets this range as the on-screen selection.
setIndent(type)	Adjusts the indent/outdent of the paragraphs spanned by the range by one step.
setList(listType)	Applies list formatting to the paragraphs spanned by this range.
setParagraphBorder(border)	Sets borders on the paragraphs spanned by this range.
setParagraphFormat(options)	Applies paragraph formatting to the paragraphs spanned by this range.
setStyle(style)	Applies a style to this range.
setTabs(tabs)	Sets the tab stops of the paragraphs spanned by this range.
setTextFormat(options)	Applies text formatting to the range.

Method details

acceptChangeTrackings()

Accepts all change-tracking entries overlapping this range.

acceptChangeTrackings(): Promise<{ processedCount: number; remainingCount: number; failedIds: string[] }>;

Returns

Promise<{ processedCount: number; remainingCount: number; failedIds: string[] }> - processing result

clearFormat()

Resets the text formatting and paragraph formatting of the range. - Paragraph formatting is reset only for paragraphs whose paragraph mark falls inside the range.

clearFormat(): Promise<void>;

Returns

Promise<void>

clearList()

Removes list formatting from the paragraphs spanned by the range.

clearList(): Promise<void>;

Returns

Promise<void>

copyFormatTo(targetRange)

Copies the style and formatting (text + paragraph) at the start position of this range to the target range.
The source is read from the start point only of this range - even if the range spans multiple paragraphs, only the first paragraph's formatting is taken.
For the same reason, paragraph formatting is applied only to the first paragraph of the target range.
If the target is an empty paragraph or a cursor, only paragraph formatting is applied and text formatting is not - there are no characters to format, and characters entered into that paragraph later do not follow the source text formatting.

copyFormatTo(targetRange: WordRange): Promise<void>;

Parameters

Name	Type	Description
targetRange	WordRange	range that receives the formatting

Returns

Promise<void>

delete()

Deletes the text of the range.

delete(): Promise<void>;

Returns

Promise<void>

getBookmarks()

Returns the list of bookmarks whose markers lie within the range.

getBookmarks(): Promise<Bookmark[]>;

Returns

Promise<Bookmark[]> - list of bookmarks (empty array if none)

getChangeTrackings()

Returns the list of change-tracking entries overlapping this range, in document order.

getChangeTrackings(): Promise<WordChangeTracking[]>;

Returns

Promise<WordChangeTracking[]> - list of change-tracking entries

getComments()

Returns the list of comments overlapping this range.

getComments(): Promise<WordComment[]>;

Returns

Promise<WordComment[]> - list of comments

getContentHtml()

Returns the paragraph content spanned by this range as HTML with formatting. - Includes paragraphs from the start to the end paragraph in document order; paragraphs inside tables are also represented as <p> elements.

getContentHtml(): Promise<{ html: string; paragraphCount: number }>;

Returns

Promise<{ html: string; paragraphCount: number }> - range HTML and paragraph count

getEndnotes()

Returns the list of endnotes within this range.

getEndnotes(): Promise<WordNote[]>;

Returns

Promise<WordNote[]> - list of endnotes

getFootnotes()

Returns the list of footnotes within this range.

getFootnotes(): Promise<WordNote[]>;

Returns

Promise<WordNote[]> - list of footnotes

getFormat()

Returns the text formatting and paragraph formatting at the start position of this range. - Even if formatting varies within the range, the direct formatting at the start position is returned.

getFormat(): Promise<{ textFormat?: TextFormat; paragraphFormat?: ParagraphFormat }>;

Returns

Promise<{ textFormat?: TextFormat; paragraphFormat?: ParagraphFormat }> - text and paragraph formatting at the start position (missing items are omitted)

getHyperlink()

Returns the hyperlink attached to this range.
The link at the start point is used; if there is none, the link at the end point is used. So a range spanning several links gives the one at the start.
Only the two end points are examined - a link that lies entirely inside the range, touching neither point, is not found.

getHyperlink(): Promise<Hyperlink>;

Returns

Promise<Hyperlink> - hyperlink object, or null if neither point has a link

getHyperlinks()

Returns the list of text hyperlinks overlapping this range.

getHyperlinks(): Promise<Hyperlink[]>;

Returns

Promise<Hyperlink[]> - list of hyperlinks (empty array if none)

getLocation()

Returns the start/end positions of this range as paragraph coordinates. - Ranges created without coordinates, such as the selection, cursor, or a footnote marker, also have their current position computed and returned. The return shape matches the getRange argument, so passing it back recreates the same range.

getLocation(): Promise<{ startParaId: string; startOffset: number; endParaId: string; endOffset: number; storyId: string }>;

Returns

Promise<{ startParaId: string; startOffset: number; endParaId: string; endOffset: number; storyId: string }> - start/end paragraph IDs, character offsets, and area ID

getNotes()

Returns the list of footnotes and endnotes within this range.

getNotes(): Promise<WordNote[]>;

Returns

Promise<WordNote[]> - list of footnotes and endnotes

getParagraph()

Returns the start paragraph of this range.
Use the returned paragraph to edit the content and formatting of the whole paragraph.
A coordinate range is not checked here - if the paragraph ID does not exist, the error surfaces when the returned paragraph is used.

getParagraph(): Promise<Paragraph>;

Returns

Promise<Paragraph> - start paragraph object

getParentSection()

Returns the section containing the start position of this range. - Returns null when the section cannot be determined outside the body, such as in headers and footers.

getParentSection(): Promise<Section>;

Returns

Promise<Section> - section object, or null if no body section is found

getShapes()

Returns the list of shapes, images, and charts within this range. - Includes both inline shapes and shapes placed in front of or behind text.

getShapes(): Promise<Shape[]>;

Returns

Promise<Shape[]> - list of shapes (pictures as WordImage, charts as WordChart; empty array if none)

getStructure()

Returns the paragraph/table structure spanned by this range. - Contains, in document order, everything from the start paragraph to the end paragraph (including tables in between).

getStructure(): Promise<{ paragraphs: { index: number; type: string; id: string; storyId: string; text?: string; rows?: number; columns?: number }[] }>;

Returns

Promise<{ paragraphs: { index: number; type: string; id: string; storyId: string; text?: string; rows?: number; columns?: number }[] }> - list of paragraph and table entries spanned by the range

getText()

Returns the text contained in this range.
Paragraph boundaries are separated by "\n". Within a single paragraph, add getLocation().startOffset to a character position in the returned text to get the paragraph character position.
This calculation cannot be used for ranges spanning multiple paragraphs.
Tabs are represented as "\t", line/page/column breaks as "\n", and objects such as footnotes and shapes as the single character "".

getText(): Promise<string>;

Returns

Promise<string> - range text ("" for an empty range/cursor)

insertBookmark(name)

Inserts a bookmark at the start position of this range. - If a bookmark with the same name exists, it is replaced. The name cannot start with a digit, special character, or space.

insertBookmark(name: string): Promise<Bookmark>;

Parameters

Name	Type	Description
name	string	bookmark name

Returns

Promise<Bookmark> - the inserted bookmark

insertColumnBreak()

Inserts a column break at this range position. - The following content starts in the next column, or on the next page if the section has a single column. Can only be inserted in the body.

insertColumnBreak(): Promise<void>;

Returns

Promise<void>

insertComment(text, options)

Inserts a comment on this range.

insertComment(
  text: string,
  options?: { authorName?: string; initials?: string }
): Promise<WordComment>;

Parameters

Name	Type	Description
text	string	comment body
options (optional)	{ authorName?: string; initials?: string }	author metadata

Returns

Promise<WordComment> - the inserted comment

insertEndnote(text)

Inserts an endnote at the end of this range. - The marker is placed in the body and the content goes into the endnote area at the end of the document.

insertEndnote(text?: string): Promise<WordNote>;

Parameters

Name	Type	Description
text (optional)	string	initial text of the endnote content (default: empty endnote)

Returns

Promise<WordNote> - the created endnote

insertFootnote(text)

Inserts a footnote at the end of this range. - The marker is placed in the body and the content goes into the footnote area at the bottom of the page.

insertFootnote(text?: string): Promise<WordNote>;

Parameters

Name	Type	Description
text (optional)	string	initial text of the footnote content (default: empty footnote)

Returns

Promise<WordNote> - the created footnote

insertHyperlink(url, options)

Attaches a hyperlink to this range.
With displayText, that text replaces the range text and carries the link; without it, the existing range text is linked as is.
An empty range has no text to link, so displayText is required there.
The link type is determined automatically from the url (web http(s)://, email mailto:, bookmark #name; https:// is assumed when no scheme is given).

insertHyperlink(
  url: string,
  options?: { tooltip?: string; displayText?: string }
): Promise<Hyperlink>;

Parameters

Name	Type	Description
url	string	link destination
options (optional)	{ tooltip?: string; displayText?: string }	hyperlink options
options.tooltip (optional)	string	mouse-over tooltip (default: url)
options.displayText (optional)	string	text to show in place of the range text (required for an empty range)

Returns

Promise<Hyperlink> - the inserted hyperlink, or null if the new id could not be identified

insertImage(options)

Inserts an image inline at the start position of this range. - Processed asynchronously regardless of the image source.

insertImage(options: { src?: string; url?: string; base64?: string; width?: number; height?: number }): Promise<Image>;

Parameters

Name	Type	Description
options	{ src?: string; url?: string; base64?: string; width?: number; height?: number }	image insert options (exactly one source among src/url/base64 is required)
options.src (optional)	string	path of an already uploaded image
options.url (optional)	string	image URL (uploaded first, then inserted)
options.base64 (optional)	string	base64 data (uploaded first, then inserted)
options.width (optional)	number	width (pt). Required with src - the original size is only known for url/base64, which are measured on upload (default: original size)
options.height (optional)	number	height (pt). Required with src - the original size is only known for url/base64, which are measured on upload (default: original size)

Returns

Promise<Image> - the inserted image

insertLineBreak()

Inserts a line break at the start position of this range. - Breaks the line while keeping the paragraph, like Shift+Enter.

insertLineBreak(): Promise<void>;

Returns

Promise<void>

insertPageBreak()

Inserts a page break at this range position. - The following content starts on the next page. Can only be inserted in the body.

insertPageBreak(): Promise<void>;

Returns

Promise<void>

insertParagraph(text, options)

Inserts a new paragraph above or below the anchor paragraph of this range.
The new paragraph inherits the anchor paragraph's direct paragraph formatting such as alignment, spacing, and indents.
To reset the inherited direct formatting, call clearFormat() on the returned paragraph.

insertParagraph(text: string, options?: { position?: InsertAt }): Promise<Paragraph>;

Parameters

Name	Type	Description
text	string	text of the new paragraph
options (optional)	{ position?: InsertAt }	insert options
options.position (optional)	InsertAt	relative to the range paragraph: "before" (above) / "after" (below) (default: InsertAt.AFTER)

Returns

Promise<Paragraph> - the newly created paragraph

insertSectionBreak(type)

Inserts a section break at this range position to create a new section. - Section breaks can only be inserted in the body (not in headers/footers/text boxes).

insertSectionBreak(type: SectionBreakType): Promise<void>;

Parameters

Name	Type	Description
type	SectionBreakType	start type of the new section (continuous: continues on the same page / nextPage: from the next page / evenPage: from the next even page / oddPage: from the next odd page)

Returns

Promise<void>

insertShape(preset, options)

Inserts a shape of the given preset into the paragraph of this range. - Use the returned shape to set formatting and placement.

insertShape(preset: ShapePreset, options?: Size): Promise<Shape>;

Parameters

Name	Type	Description
preset	ShapePreset	basic shape of the shape (e.g. "rect", "ellipse", "roundRect")
options (optional)	Size	size (pt; an omitted axis defaults to 75)

Returns

Promise<Shape> - the inserted shape

insertSymbol(charCode, options)

Inserts a symbol at the start position of this range.
font not specified: inserts the Unicode character as plain text.
font specified: inserts it as a symbol glyph of that font.

insertSymbol(charCode: string | number, options?: { font?: string }): Promise<void>;

Parameters

Name	Type	Description
charCode	string | number	Unicode code point (hex string "2605" | "0x2605" | number 0x2605)
options (optional)	{ font?: string }	when font is specified, inserts the symbol in that font

Returns

Promise<void>

insertTab()

Inserts a tab character at the start position of this range. - Tab stop positions are set separately with setTabs().

insertTab(): Promise<void>;

Returns

Promise<void>

insertTable(rows, columns, options)

Inserts a table relative to the paragraph of the range. - Cannot insert inside a table cell (nested tables are not supported - an error occurs if the insertion point is inside a cell).

insertTable(
  rows: number,
  columns: number,
  options?: { position?: InsertAt; values?: string[][] }
): Promise<Table>;

Parameters

Name	Type	Description
rows	number	number of rows
columns	number	number of columns
options (optional)	{ position?: InsertAt; values?: string[][] }	insert options
options.position (optional)	InsertAt	relative to the range paragraph: "before" (above) / "after" (below) (default: InsertAt.AFTER)
options.values (optional)	string[][]	cell values to fill right after creation (2D array; exceeding the table size raises an error before issuing)

Returns

Promise<Table> - the inserted table

insertText(text, options)

Inserts text into this range.
replace not specified: inserts at one end point of the range (the original text remains even for a span). position determines which end.
replace: true: replaces the range text with the new text (for a single point, inserts there; position is ignored). Handles text only and leaves formatting as-is. Apply formatting changes separately to the returned range.

insertText(text: string, options?: { position?: InsertAt; replace?: boolean }): Promise<Range>;

Parameters

Name	Type	Description
text	string	text to insert
options (optional)	{ position?: InsertAt; replace?: boolean }	insert/replace options
options.position (optional)	InsertAt	relative to the range: "before" (start point, before the match) / "after" (end point, after the match). Ignored when replace:true. (default: InsertAt.BEFORE)
options.replace (optional)	boolean	if true, replaces the range text with the new text (position ignored)

Returns

Promise<Range> - range of the newly inserted or replaced text (setTextFormat etc. can be applied to it directly)

insertTextbox(options)

Inserts a text box into the paragraph of the range.

insertTextbox(options?: Size & { text?: String }): Promise<{ shape: WordShape; storyId: string; paragraphId: string }>;

Parameters

Name	Type	Description
options (optional)	Size & { text?: String }	text box creation options (an omitted size axis defaults to 100; text is the initial content)

Returns

Promise<{ shape: WordShape; storyId: string; paragraphId: string }> - creation result (shape: shape object / storyId: text box area ID / paragraphId: first paragraph ID)

insertWebVideo(url, options)

Inserts a web video inline at the start position of this range.
Supports YouTube and 3DS 3DEXPERIENCE URLs and is processed asynchronously.
If the preview image cannot be fetched, a fallback image is used.

insertWebVideo(url: string, options?: Size): Promise<Image>;

Parameters

Name	Type	Description
url	string	web video URL (YouTube / 3DS 3DEXPERIENCE)
options (optional)	Size	size (pt) (default: thumbnail original size)

Returns

Promise<Image> - the inserted web video image object

isCollapsed()

Checks whether this range is empty, with the same start and end. - Returns true for a cursor-only range, and false for a range containing selected characters or a search result.

isCollapsed(): Promise<boolean>;

Returns

Promise<boolean> - true if the range is empty

rejectChangeTrackings()

Rejects all change-tracking entries overlapping this range.

rejectChangeTrackings(): Promise<{ processedCount: number; remainingCount: number; failedIds: string[] }>;

Returns

Promise<{ processedCount: number; remainingCount: number; failedIds: string[] }> - processing result

search(query, options)

Finds text or special characters (page break/column break/line break/tab/symbol) within this range and returns editable ranges.

search(
  query: string | { character: SpecialCharacter },
  options?: { caseSensitive?: boolean; wholeWord?: boolean }
): Promise<Range[]>;

Parameters

Name	Type	Description
query	string | { character: SpecialCharacter }	a string searches text; a \{ character \} object searches special characters
options (optional)	{ caseSensitive?: boolean; wholeWord?: boolean }	text search options (ignored for special character search)
options.caseSensitive (optional)	boolean	case-sensitive matching (default: false)
options.wholeWord (optional)	boolean	whole-word search (a match is accepted only when bounded by whitespace, punctuation, or a document boundary) (default: false)

Returns

Promise<Range[]> - list of matched ranges within this range (empty array if none)

select(mode)

Sets this range as the on-screen selection. - Does not change document content.

select(mode?: SelectionMode): Promise<void>;

Parameters

Name	Type	Description
mode (optional)	SelectionMode	"select" (whole range) / "start" (cursor at the start point) / "end" (cursor at the end point) (default: SelectionMode.SELECT)

Returns

Promise<void>

setIndent(type)

Adjusts the indent/outdent of the paragraphs spanned by the range by one step.
For list paragraphs the list level moves; for non-list paragraphs the paragraph left margin moves.
Even if the start paragraph is the first item of a list, only that item's level moves.

setIndent(type: IndentType): Promise<void>;

Parameters

Name	Type	Description
type	IndentType	"indent"|"outdent"

Returns

Promise<void>

setList(listType)

Applies list formatting to the paragraphs spanned by this range.
An empty range applies to the paragraph containing the cursor. If multiple paragraphs are included, all of them are affected.
If the cursor is inside an existing list, items of the same list at the same level change too. Multi-level lists are updated as a whole.

setList(listType: ListType): Promise<void>;

Parameters

Name	Type	Description
listType	ListType	list type to apply. Choose from the built-in bullet, numbered, and multi-level lists.

Returns

Promise<void>

setParagraphBorder(border)

Sets borders on the paragraphs spanned by this range. - Uses the same Border format as cell borders; location specifies which sides to apply.

setParagraphBorder(border: Border): Promise<void>;

Parameters

Name	Type	Description
border	Border	border value (shared by paragraphs, cells, and pages)

Returns

Promise<void>

setParagraphFormat(options)

Applies paragraph formatting to the paragraphs spanned by this range. - Only the specified fields change; null removes that property so the style's formatting applies.

setParagraphFormat(options: ParagraphFormat): Promise<void>;

Parameters

Name	Type	Description
options	ParagraphFormat	paragraph formatting to apply

Returns

Promise<void>

setStyle(style)

Applies a style to this range. - Existing direct formatting is reset. A paragraph style applies to the paragraphs spanned by the range; a character style applies to the range text.

setStyle(style: Style | string | null): Promise<void>;

Parameters

Name	Type	Description
style	Style | string | null	built-in styles use the Style enum (value = key); custom document styles use the style value from getStyles(). null removes the character style only, leaving the paragraph style in place

Returns

Promise<void>

setTabs(tabs)

Sets the tab stops of the paragraphs spanned by this range. - Replaces the existing setting with the given array; an empty array removes all tab stops.

setTabs(tabs: TabStop[]): Promise<void>;

Parameters

Name	Type	Description
tabs	TabStop[]	array of tab stops

Returns

Promise<void>

setTextFormat(options)

Applies text formatting to the range.

setTextFormat(options: TextFormat): Promise<void>;

Parameters

Name	Type	Description
options	TextFormat	text formatting to apply (only the specified fields change; passing null instead of a value removes that property and reverts to style inheritance)

Returns

Promise<void>