Word.Paragraph

Word.Paragraph is an object type of the Word module (Office.word(iframe)). 44 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.getParagraph(paragraphId), Body.getParagraph(index), Body.getParagraphs(), Body.insertParagraph(text, options), Range.getParagraph(), Range.insertParagraph(text, options), TableCell.getParagraph(index), TableCell.getParagraphs()
• Every method returns a Promise; signatures use TypeScript notation.

Methods

Method	Description
acceptChangeTrackings()	Accepts all change tracking entries overlapping this paragraph.
clearFormat()	Resets the text formatting and paragraph formatting of the entire paragraph.
clearList()	Removes the list from this paragraph.
delete()	Deletes the paragraph.
getChangeTrackings()	Returns the list of change tracking entries overlapping this paragraph.
getComments()	Returns the list of comments overlapping this paragraph's range.
getContentHtml()	Returns the content of this paragraph as HTML with formatting.
getEndnotes()	Returns the list of endnotes in this paragraph.
getFootnotes()	Returns the list of footnotes in this paragraph.
getId()	Returns the paragraph ID.
getList()	Returns the list of this paragraph.
getNextSibling()	Returns the immediately following paragraph.
getNotes()	Returns the list of footnotes/endnotes in this paragraph.
getParentBody()	Returns the area (body/header/footer, etc.) this paragraph belongs to.
getParentTable()	Returns the nearest table this paragraph belongs to.
getParentTableCell()	Returns the nearest table cell this paragraph belongs to.
getPreviousSibling()	Returns the immediately preceding paragraph.
getRange(startOffset, endOffset)	Returns the range for the given character position span within this paragraph.
getStructure()	Returns the structure information of this paragraph.
getText()	Returns the text of the paragraph.
insertColumnBreak(options)	Inserts a column break into the paragraph.
insertEndnote(text, options)	Inserts an endnote at the paragraph position.
insertFootnote(text, options)	Inserts a footnote at the paragraph position.
insertImage(options)	Inserts an image into the paragraph, placed inline like a character.
insertLineBreak(options)	Inserts a line break into the paragraph.
insertPageBreak(options)	Inserts a page break into the paragraph.
insertParagraph(text, options)	Inserts a new paragraph above or below this paragraph, or splits the paragraph at the given character position.
insertSectionBreak(type, options)	Inserts a section break at the paragraph position to create a new section.
insertShape(preset, options)	Inserts a shape of the given preset into the paragraph.
insertSymbol(charCode, options)	Inserts a symbol into the paragraph.
insertTab(options)	Inserts a tab character into the paragraph.
insertTable(rows, columns, options)	Inserts a table above or below this paragraph, or splits the paragraph at a character position and inserts the table between the parts.
insertText(text, options)	Inserts text into the paragraph or replaces the entire paragraph content.
insertTextbox(options)	Inserts a text box into the paragraph.
insertWebVideo(url, options)	Inserts a web video into the paragraph, placed inline like a character.
rejectChangeTrackings()	Rejects all change tracking entries overlapping this paragraph.
select(mode)	Sets this paragraph as the on-screen selection.
setIndent(type)	Adjusts indent/outdent by one level.
setList(listType)	Applies the given list format to this paragraph.
setParagraphBorder(border)	Sets the border of this paragraph.
setParagraphFormat(options)	Applies the given paragraph formatting to this paragraph.
setStyle(style)	Applies a style to this paragraph.
setTabs(tabs)	Sets the tab stop positions of this paragraph.
setTextFormat(options)	Applies text formatting to the entire text of the paragraph.

Method details

acceptChangeTrackings()

Accepts all change tracking entries overlapping this paragraph.

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 entire paragraph.

clearFormat(): Promise<void>;

Returns

Promise<void>

clearList()

Removes the list from this paragraph. - To remove lists from multiple paragraphs at once, use clearList of WordRange.

clearList(): Promise<void>;

Returns

Promise<void>

delete()

Deletes the paragraph. - If no other paragraph follows, keeps the paragraph and deletes only its characters.

delete(): Promise<void>;

Returns

Promise<void>

getChangeTrackings()

Returns the list of change tracking entries overlapping this paragraph.

getChangeTrackings(): Promise<WordChangeTracking[]>;

Returns

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

getComments()

Returns the list of comments overlapping this paragraph's range.

getComments(): Promise<WordComment[]>;

Returns

Promise<WordComment[]> - list of comments

getContentHtml()

Returns the content of this paragraph as HTML with formatting. - The paragraph is represented as a <p> element.

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

Returns

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

getEndnotes()

Returns the list of endnotes in this paragraph.

getEndnotes(): Promise<WordNote[]>;

Returns

Promise<WordNote[]> - list of endnotes

getFootnotes()

Returns the list of footnotes in this paragraph.

getFootnotes(): Promise<WordNote[]>;

Returns

Promise<WordNote[]> - list of footnotes

getId()

Returns the paragraph ID.

getId(): Promise<string>;

Returns

Promise<string> - paragraph ID

getList()

Returns the list of this paragraph. - Used to change the list level and restart numbering.

getList(): Promise<List>;

Returns

Promise<List> - list handle; null if the paragraph is not a list item

getNextSibling()

Returns the immediately following paragraph. - Returns null if the following element is not a paragraph (e.g. a table) or does not exist. Does not cross section boundaries.

getNextSibling(): Promise<Paragraph>;

Returns

Promise<Paragraph> - the next paragraph; null if none or the following element is not a paragraph

getNotes()

Returns the list of footnotes/endnotes in this paragraph.

getNotes(): Promise<WordNote[]>;

Returns

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

getParentBody()

Returns the area (body/header/footer, etc.) this paragraph belongs to.

getParentBody(): Promise<Body>;

Returns

Promise<Body> - the area this paragraph belongs to

getParentTable()

Returns the nearest table this paragraph belongs to. - Returns null for a paragraph outside a table. For nested tables, returns the inner table.

getParentTable(): Promise<Table>;

Returns

Promise<Table> - the parent table object; null if outside a table

getParentTableCell()

Returns the nearest table cell this paragraph belongs to. - Returns null for a paragraph outside a cell. For nested tables, returns the inner cell.

getParentTableCell(): Promise<TableCell>;

Returns

Promise<TableCell> - the parent cell object; null if outside a cell

getPreviousSibling()

Returns the immediately preceding paragraph. - Returns null if the preceding element is not a paragraph (e.g. a table) or does not exist. Does not cross section boundaries.

getPreviousSibling(): Promise<Paragraph>;

Returns

Promise<Paragraph> - the previous paragraph; null if none or the preceding element is not a paragraph

getRange(startOffset, endOffset)

Returns the range for the given character position span within this paragraph.

getRange(startOffset?: number, endOffset?: number): Promise<Range>;

Parameters

Name	Type	Description
startOffset (optional)	number	start character position (0-based) (default: paragraph start)
endOffset (optional)	number	end character position (default: paragraph end)

Returns

Promise<Range> - range object bound to the offset span within the paragraph

getStructure()

Returns the structure information of this paragraph. - Includes index, type, paragraph ID, area ID and text.

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

Returns

Promise<{ paragraphs: { index: number; type: string; id: string; storyId: string; text: string }[] }> - a list containing this single paragraph entry

getText()

Returns the text of the paragraph.
Character positions computed from the returned text are used as the offset of insertText() or the character positions of getRange().
A tab is represented as "\t", line/page/column breaks as "\n", and objects such as footnotes and shapes as the single character "\uFFFC".
The line break that marks the end of the paragraph is not included.

getText(): Promise<string>;

Returns

Promise<string> - the concatenated text of the characters in the paragraph ("" if none)

insertColumnBreak(options)

Inserts a column break into the paragraph. - 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(options?: { offset?: number; position?: InsertAt }): Promise<void>;

Parameters

Name	Type	Description
options (optional)	{ offset?: number; position?: InsertAt }	insertion position options
options.offset (optional)	number	character position within the paragraph (0-based); takes precedence over position
options.position (optional)	InsertAt	insertion position (when offset is absent). start (paragraph start) | end (paragraph end) (default: InsertAt.START)

Returns

Promise<void>

insertEndnote(text, options)

Inserts an endnote at the paragraph position.

insertEndnote(
  text?: string,
  options?: { offset?: number; position?: InsertAt }
): Promise<WordNote>;

Parameters

Name	Type	Description
text (optional)	string	initial text of the endnote content (default: empty endnote)
options (optional)	{ offset?: number; position?: InsertAt }	insertion position options
options.offset (optional)	number	character position within the paragraph (0-based); takes precedence over position
options.position (optional)	InsertAt	insertion position (when offset is absent). start (paragraph start) | end (paragraph end) (default: InsertAt.START)

Returns

Promise<WordNote> - the created endnote object

insertFootnote(text, options)

Inserts a footnote at the paragraph position.

insertFootnote(
  text?: string,
  options?: { offset?: number; position?: InsertAt }
): Promise<WordNote>;

Parameters

Name	Type	Description
text (optional)	string	initial text of the footnote content (default: empty footnote)
options (optional)	{ offset?: number; position?: InsertAt }	insertion position options
options.offset (optional)	number	character position within the paragraph (0-based); takes precedence over position
options.position (optional)	InsertAt	insertion position (when offset is absent). start (paragraph start) | end (paragraph end) (default: InsertAt.START)

Returns

Promise<WordNote> - the created footnote object

insertImage(options)

Inserts an image into the paragraph, placed inline like a character. - Processed asynchronously regardless of the image source.

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

Parameters

Name	Type	Description
options	{ src?: string; url?: string; base64?: string; width?: number; height?: number; offset?: number; position?: InsertAt }	image insertion 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) (default: original size)
options.height (optional)	number	height (pt) (default: original size)
options.offset (optional)	number	character position within the paragraph (0-based); takes precedence over position
options.position (optional)	InsertAt	insertion position (when offset is absent). start (paragraph start) | end (paragraph end) (default: InsertAt.START)

Returns

Promise<Image> - the inserted image

insertLineBreak(options)

Inserts a line break into the paragraph. - Breaks the line while keeping the paragraph, like Shift+Enter.

insertLineBreak(options?: { offset?: number; position?: InsertAt }): Promise<void>;

Parameters

Name	Type	Description
options (optional)	{ offset?: number; position?: InsertAt }	insertion position options
options.offset (optional)	number	character position within the paragraph (0-based); a position past the end of the paragraph is adjusted to the paragraph end. takes precedence over position
options.position (optional)	InsertAt	insertion position (when offset is absent). start (paragraph start) | end (paragraph end) (default: InsertAt.START)

Returns

Promise<void>

insertPageBreak(options)

Inserts a page break into the paragraph. - The following content starts on the next page. Can only be inserted in the body.

insertPageBreak(options?: { offset?: number; position?: InsertAt }): Promise<void>;

Parameters

Name	Type	Description
options (optional)	{ offset?: number; position?: InsertAt }	insertion position options
options.offset (optional)	number	character position within the paragraph (0-based); takes precedence over position
options.position (optional)	InsertAt	insertion position (when offset is absent). start (paragraph start) | end (paragraph end) (default: InsertAt.START)

Returns

Promise<void>

insertParagraph(text, options)

Inserts a new paragraph above or below this paragraph, or splits the paragraph at the given character position.
The new paragraph inherits this paragraph's direct paragraph formatting such as alignment, spacing and indentation.
To reset the inherited direct formatting, call clearFormat() on the returned paragraph.

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

Parameters

Name	Type	Description
text	string	text of the new paragraph (empty string creates an empty paragraph - a pure split when offset is given)
options (optional)	{ offset?: number; position?: InsertAt }	insertion options
options.offset (optional)	number	splits at the character position within the paragraph (0-based); the following content is preserved as the new paragraph. a position past the end of the paragraph is adjusted to the paragraph end. position is ignored when specified
options.position (optional)	InsertAt	for sibling insertion, "before" (above) / "after" (below) relative to this paragraph (default: InsertAt.AFTER)

Returns

Promise<Paragraph> - the newly created paragraph object

insertSectionBreak(type, options)

Inserts a section break at the paragraph position to create a new section. - Section breaks can only be inserted in the body (not in header/footer/text box).

insertSectionBreak(
  type: SectionBreakType,
  options?: { offset?: number; position?: InsertAt }
): Promise<void>;

Parameters

Name	Type	Description
type	SectionBreakType	start type of the new section (continuous: continues / nextPage: from the next page / evenPage: from the next even page / oddPage: from the next odd page)
options (optional)	{ offset?: number; position?: InsertAt }	insertion position options
options.offset (optional)	number	character position within the paragraph (0-based); takes precedence over position
options.position (optional)	InsertAt	insertion position (when offset is absent). start (paragraph start) | end (paragraph end) (default: InsertAt.START)

Returns

Promise<void>

insertShape(preset, options)

Inserts a shape of the given preset into the paragraph. - After insertion, use the returned shape to set formatting and placement.

insertShape(
  preset: ShapePreset,
  options?: { width?: number; height?: number; offset?: number; position?: InsertAt }
): Promise<Shape>;

Parameters

Name	Type	Description
preset	ShapePreset	base shape of the shape (e.g. "rect", "ellipse", "roundRect")
options (optional)	{ width?: number; height?: number; offset?: number; position?: InsertAt }	shape insertion options
options.width (optional)	number	width (pt) (default: 75)
options.height (optional)	number	height (pt) (default: 75)
options.offset (optional)	number	character position within the paragraph (0-based); takes precedence over position
options.position (optional)	InsertAt	insertion position (when offset is absent). start (paragraph start) | end (paragraph end) (default: InsertAt.START)

Returns

Promise<Shape> - the inserted shape

insertSymbol(charCode, options)

Inserts a symbol into the paragraph.
font not specified: inserts the Unicode character as plain text.
font specified: inserts the symbol glyph of that font.

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

Parameters

Name	Type	Description
charCode	string | number	Unicode code point (hex string "2605" | "0x2605" | number 0x2605)
options (optional)	{ font?: string; offset?: number; position?: InsertAt }	symbol insertion options
options.font (optional)	string	if specified, inserts the symbol glyph of that font
options.offset (optional)	number	character position within the paragraph (0-based); takes precedence over position
options.position (optional)	InsertAt	insertion position (when offset is absent). start (paragraph start) | end (paragraph end) (default: InsertAt.START)

Returns

Promise<void>

insertTab(options)

Inserts a tab character into the paragraph. - Tab stop positions are set separately with setTabs().

insertTab(options?: { offset?: number; position?: InsertAt }): Promise<void>;

Parameters

Name	Type	Description
options (optional)	{ offset?: number; position?: InsertAt }	insertion position options
options.offset (optional)	number	character position within the paragraph (0-based); a position past the end of the paragraph is adjusted to the paragraph end. takes precedence over position
options.position (optional)	InsertAt	insertion position (when offset is absent). start (paragraph start) | end (paragraph end) (default: InsertAt.START)

Returns

Promise<void>

insertTable(rows, columns, options)

Inserts a table above or below this paragraph, or splits the paragraph at a character position and inserts the table between the parts. - Cannot be inserted inside a table cell (nested tables are not supported - an error is thrown if the insertion point is inside a cell).

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

Parameters

Name	Type	Description
rows	number	number of rows
columns	number	number of columns
options (optional)	{ offset?: number; position?: InsertAt; values?: string[][] }	insertion options
options.offset (optional)	number	splits at the character position within the paragraph (0-based) and inserts the table between the parts; the following content is preserved as a new paragraph. position is ignored when specified
options.position (optional)	InsertAt	for sibling insertion, "before" (above) / "after" (below) relative to this paragraph (default: InsertAt.AFTER)
options.values (optional)	string[][]	cell values to fill right after creation (2D array; an error is thrown before execution if it exceeds the table size)

Returns

Promise<Table> - the inserted table object

insertText(text, options)

Inserts text into the paragraph or replaces the entire paragraph content. - Formatting is preserved. To change or reset formatting, use setTextFormat(), clearFormat() or setStyle() on the returned range.

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

Parameters

Name	Type	Description
text	string	text to insert
options (optional)	{ offset?: number; position?: InsertAt; replace?: boolean }	insert/replace options
options.offset (optional)	number	character position within the paragraph (0-based); takes precedence over position
options.position (optional)	InsertAt	append position (when offset is absent). start (paragraph start) | end (paragraph end) (default: InsertAt.START)
options.replace (optional)	boolean	if true, replaces the entire paragraph content with the new text (position arguments ignored) (default: false)

Returns

Promise<Range> - range of the text just inserted (or replaced, when replacing)

insertTextbox(options)

Inserts a text box into the paragraph.

insertTextbox(options?: { width?: number; height?: number; text?: string; offset?: number; position?: InsertAt }): Promise<{ shape: WordShape; storyId: string; paragraphId: string }>;

Parameters

Name	Type	Description
options (optional)	{ width?: number; height?: number; text?: string; offset?: number; position?: InsertAt }	text box insertion options
options.width (optional)	number	width (pt) (default: 75)
options.height (optional)	number	height (pt) (default: 75)
options.text (optional)	string	initial content text
options.offset (optional)	number	character position within the paragraph (0-based); takes precedence over position
options.position (optional)	InsertAt	insertion position (when offset is absent). start (paragraph start) | end (paragraph end) (default: InsertAt.START)

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 into the paragraph, placed inline like a character.
Supports YouTube and 3DS 3DEXPERIENCE URLs and is processed asynchronously.
Uses a fallback image if the preview image cannot be fetched.

insertWebVideo(
  url: string,
  options?: { width?: number; height?: number; offset?: number; position?: InsertAt }
): Promise<Image>;

Parameters

Name	Type	Description
url	string	web video URL (YouTube / 3DS 3DEXPERIENCE)
options (optional)	{ width?: number; height?: number; offset?: number; position?: InsertAt }	web video insertion options
options.width (optional)	number	width (pt) (default: original thumbnail size)
options.height (optional)	number	height (pt) (default: original thumbnail size)
options.offset (optional)	number	character position within the paragraph (0-based); takes precedence over position
options.position (optional)	InsertAt	insertion position (when offset is absent). start (paragraph start) | end (paragraph end) (default: InsertAt.START)

Returns

Promise<Image> - the inserted web video image object

rejectChangeTrackings()

Rejects all change tracking entries overlapping this paragraph.

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

Returns

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

select(mode)

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

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

Parameters

Name	Type	Description
mode (optional)	SelectionMode	"select" (entire paragraph) / "start" (cursor at paragraph start) / "end" (cursor at paragraph end) (default: SelectionMode.SELECT)

Returns

Promise<void>

setIndent(type)

Adjusts indent/outdent by one level.
For a list paragraph the list level moves; otherwise the paragraph's left indent moves.
Even for 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 the given list format to this paragraph.
When applied to an existing list, items at the same level of the same list change as well.
Applying a multilevel list affects the entire list.
After applying, change the list level with setLevel() on the list obtained from getList().

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

Parameters

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

Returns

Promise<void>

setParagraphBorder(border)

Sets the border of this paragraph. - Uses the same Border format as cell borders.

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

Parameters

Name	Type	Description
border	Border	border value

Returns

Promise<void>

setParagraphFormat(options)

Applies the given paragraph formatting to this paragraph. - Only the specified fields are changed. Text formatting is set with setTextFormat().

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 paragraph.
Applying a style resets the existing direct formatting.
A paragraph style is applied to the paragraph; a character style is applied to the entire text of the paragraph.

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

Parameters

Name	Type	Description
style	Style | string | null	Style enum for built-in styles (value = key), or the style value from getStyles() for custom document styles. null removes the style (reverts to default)

Returns

Promise<void>

setTabs(tabs)

Sets the tab stop positions of this paragraph. - 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 entire text of the paragraph.

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

Parameters

Name	Type	Description
options	TextFormat	text formatting to apply

Returns

Promise<void>