Word.Selection class

Package:: word

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Represents a selected range or the insertion point in a Word document.

Note: Range objects share many of the same methods and properties as Selection objects. Using Range objects is preferable for manipulating a document when there isn't a reason to physically change the current selection.

Extends: OfficeExtension.ClientObject

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Properties

borders	Returns a `BorderUniversalCollection` object that represents all the borders for the objects in the selection.
characters	Returns a `RangeScopedCollection` object that represents each character in the selection.
comments	Returns a `CommentCollection` object that represents all the comments in the selection.
context	The request context associated with the object. This connects the add-in's process to the Office host application's process.
end	Specifies the ending character position of the selection.
fields	Returns a `FieldCollection` object that represents all the fields in the selection.
fitTextWidth	Specifies the width in which Word fits the text in the current selection.
font	Returns the `Font` object that represents the character formatting of the selection.
formattedText	Specifies a `Range` object that includes the formatted text in the range or selection.
hasNoProofing	Returns whether the spelling and grammar checker ignores the selected text. If the selected text contains a mix of proofed and un-proofed content, this API returns `null`.
isActive	Returns whether the selection in the specified window or pane is active.
isColumnSelectModeActive	Specifies whether column selection mode is active.
isEndOfRowMark	Returns whether the selection is at the end-of-row mark in a table.
isExtendModeActive	Specifies whether Extend mode is active.
isInsertionPointAtEndOfLine	Returns whether the insertion point is at the end of a line.
isStartActive	Specifies whether the beginning of the selection is active.
languageDetected	Specifies whether Word has detected the language of the selected text.
languageId	Returns the language for the selection.
languageIdFarEast	Returns the East Asian language for the selection.
languageIdOther	Returns the language for the selection that isn't classified as an East Asian language.
orientation	Specifies the orientation of text in the selection.
paragraphs	Returns a `ParagraphCollection` object that represents all the paragraphs in the selection.
range	Returns the `Range` object for the portion of the document contained in the selection.
sections	Returns the `SectionCollection` object in the selection.
sentences	Returns the `RangeScopedCollection` object for each sentence in the selection.
shading	Returns the `ShadingUniversal` object for the shading formatting for the selection.
start	Specifies the starting character position of the selection.
storyLength	Returns the number of characters in the story that contains the selection.
storyType	Returns the story type for the selection.
tables	Returns the `TableCollection` object in the selection.
text	Specifies the text in the selection.
topLevelTables	Returns the tables at the outermost nesting level in the current selection.
type	Returns the selection type.
words	Returns the `RangeScopedCollection` object that represents each word in the selection.

Methods

calculate()	Calculates the first mathematical expression within the selection.
cancelMode()	Cancels a mode such as extend or column select. This is equivalent to pressing the Esc key.
clearCharacterStyleFormatting()	Removes character formatting applied through character styles.
clearFormatting()	Removes character and paragraph formatting from the selection.
clearManualCharacterFormatting()	Removes manually applied character formatting from the selected text.
clearManualParagraphFormatting()	Removes manually applied paragraph formatting from the selected text.
clearParagraphFormatting()	Removes all paragraph formatting from the selected text.
clearParagraphStyle()	Removes paragraph formatting applied through paragraph styles.
collapse(direction)	Collapses the selection to the starting or ending position.
collapse(direction)	Collapses the selection to the starting or ending position.
convertToTable(options)	Converts text within a range to a table.
copyAsPictureToClipboard()	Copies the selection to the Clipboard as a picture.
copyFormat()	Copies the character formatting of the first character in the selected text.
copyToClipboard()	Copies the selection to the Clipboard.
createTextBox()	Adds a default-sized text box around the selection.
cut()	Removes the selected content from the document and moves it to the Clipboard.
delete(options)	Deletes the specified number of characters or words.
detectLanguage()	Analyzes the selected text to determine the language that it's written in.
expand(unit)	Expands the selection.
expand(unit)	Expands the selection.
expandToWholeStory()	Expands the selection to include the entire story.
extend(character)	Turns on extend mode, or if extend mode is already on, extends the selection to the next larger unit of text.
extend(character)	Turns on extend mode, or if extend mode is already on, extends the selection to the next larger unit of text.
getNextRange(options)	Returns a `Range` object that represents the next unit relative to the selection.
getPreviousRange(options)	Returns a `Range` object that represents the previous unit relative to the selection.
goTo(options)	Returns a `Range` object that represents the area specified by the `options` and moves the insertion point to the character position immediately preceding the specified item.
goToNext(what)	Returns a `Range` object that refers to the start position of the next item or ___location specified by the `what` argument and moves the selection to the specified item.
goToNext(what)	Returns a `Range` object that refers to the start position of the next item or ___location specified by the `what` argument and moves the selection to the specified item.
goToPrevious(what)	Returns a `Range` object that refers to the start position of the previous item or ___location specified by the `what` argument and moves the selection to the specified item.
goToPrevious(what)	Returns a `Range` object that refers to the start position of the previous item or ___location specified by the `what` argument and moves the selection to the specified item.
insertAfter(text)	Inserts the specified text at the end of the range or selection.
insertBefore(text)	Inserts the specified text before the selection.
insertCells(shiftCells)	Adds cells to an existing table.
insertCells(shiftCells)	Adds cells to an existing table.
insertColumnsLeft()	Inserts columns to the left of the column that contains the selection.
insertColumnsRight()	Inserts columns to the right of the current selection.
insertDateTime(options)	Inserts the current date or time, or both, either as text or as a TIME field.
insertFormula(options)	Inserts a Formula field at the selection.
insertNewPage()	Inserts a new page at the position of the insertion point.
insertParagraphAfter()	Inserts a paragraph mark after the selection.
insertParagraphBefore()	Inserts a new paragraph before the selection or range.
insertParagraphStyleSeparator()	Inserts a special hidden paragraph mark that allows Word to join paragraphs formatted using different paragraph styles.
insertRowsAbove(numRows)	Inserts rows above the current selection.
insertRowsBelow(numRows)	Inserts rows below the current selection.
insertSymbol(characterNumber, options)	Inserts a symbol in place of the specified selection.
insertText(Text)	Inserts the specified text.
insertXml(xml, transform)	Inserts the specified XML into the document at the cursor, replacing any selected text.
isEqual(range)	Returns whether the selection is equal to the specified range.
isInRange(range)	Returns `true` if the selection is contained within the specified range.
isInStory(range)	Returns whether the selection is in the same story as the specified range.
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.
move(options)	Collapses the selection to its start or end position and then moves the collapsed object by the specified number of units.
moveDown(options)	Moves the selection down.
moveEnd(options)	Moves the ending character position of the range or selection.
moveEndUntil(characters, count)	Moves the end position of the selection until any of the specified characters are found in the document.
moveEndWhile(characters, count)	Moves the ending character position of the selection while any of the specified characters are found in the document.
moveLeft(options)	Moves the selection to the left.
moveRight(options)	Moves the selection to the right.
moveStart(options)	Moves the start position of the selection.
moveStartUntil(characters, count)	Moves the start position of the selection until one of the specified characters is found in the document.
moveStartWhile(characters, count)	Moves the start position of the selection while any of the specified characters are found in the document.
moveUntil(characters, count)	Moves the selection until one of the specified characters is found in the document.
moveUp(options)	Moves the selection up.
moveWhile(characters, count)	Moves the selection while any of the specified characters are found in the document.
nextField()	Selects the next field.
nextSubdocument()	Moves the selection to the next subDocument.
pasteAndFormat(type)	Pastes the content from clipboard and formats them as specified.
pasteAndFormat(type)	Pastes the content from clipboard and formats them as specified.
pasteExcelTable(linkedToExcel, wordFormatting, rtf)	Pastes and formats a Microsoft Excel table.
pasteFormat()	Applies formatting copied with the `copyFormat` method to the selection.
pasteTableCellsAppendTable()	Merges pasted cells into an existing table by inserting the pasted rows between the selected rows.
pasteTableCellsAsNestedTable()	Pastes a cell or group of cells as a nested table into the selection.
previousField()	Selects and returns the previous field.
previousSubdocument()	Moves the selection to the previous subDocument.
replaceParagraph()	Replaces the selection with a new paragraph.
select()	Selects the current text.
selectCell()	Selects the entire cell containing the current selection when the selection is in a table.
selectColumn()	Selects the column that contains the insertion point, or selects all columns that contain the selection when the selection is in a table.
selectCurrentAlignment()	Extends the selection forward until text with a different paragraph alignment is encountered.
selectCurrentColor()	Extends the selection forward until text with a different color is encountered.
selectCurrentFont()	Extends the selection forward until text in a different font or font size is encountered.
selectCurrentIndent()	Extends the selection forward until text with different left or right paragraph indents is encountered.
selectCurrentSpacing()	Extends the selection forward until a paragraph with different line spacing is encountered.
selectCurrentTabs()	Extends the selection forward until a paragraph with different tab stops is encountered.
selectRow()	Selects the row that contains the insertion point, or selects all rows that contain the selection when the selection is in a table.
setRange(start, end)	Sets the starting and ending character positions for the selection. Character position values start at the beginning of the story, with the first value being 0. All characters are counted, including nonprinting characters. Hidden characters are counted even if they're not displayed.
shrink()	Shrinks the selection to the next smaller unit of text. The unit progression for this method is as follows: entire document, section, paragraph, sentence, word, insertion point.
shrinkDiscontiguousSelection()	Cancels the selection of all but the most recently selected text when the current selection contains multiple, unconnected selections.
splitTable()	Inserts an empty paragraph above the first row in the selection. If the selection isn't in the first row of the table, the table is split into two tables. If the selection isn't in a table, an error occurs.
toggleCharacterCode()	Switches the selection between a Unicode character and its corresponding hexadecimal value.
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 `Word.Selection` object is an API object, the `toJSON` method returns a plain JavaScript object (typed as `Word.Interfaces.SelectionData`) 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. If this object is part of a collection, you should also track the parent collection.
typeBackspace()	Deletes the character preceding the selection (if collapsed) or the insertion point.
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

borders

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Returns a BorderUniversalCollection object that represents all the borders for the objects in the selection.

readonly borders: Word.BorderUniversalCollection;

Property Value

Word.BorderUniversalCollection

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

characters

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Returns a RangeScopedCollection object that represents each character in the selection.

readonly characters: Word.RangeScopedCollection;

Property Value

Word.RangeScopedCollection

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

comments

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Returns a CommentCollection object that represents all the comments in the selection.

readonly comments: Word.CommentCollection;

Property Value

Word.CommentCollection

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

context

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

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

Word.RequestContext

end

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Specifies the ending character position of the selection.

end: number;

Property Value

number

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

fields

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Returns a FieldCollection object that represents all the fields in the selection.

readonly fields: Word.FieldCollection;

Property Value

Word.FieldCollection

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

fitTextWidth

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Specifies the width in which Word fits the text in the current selection.

fitTextWidth: number;

Property Value

number

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

font

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Returns the Font object that represents the character formatting of the selection.

readonly font: Word.Font;

Property Value

Word.Font

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

formattedText

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Specifies a Range object that includes the formatted text in the range or selection.

formattedText: Word.Range;

Property Value

Word.Range

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

hasNoProofing

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Returns whether the spelling and grammar checker ignores the selected text. If the selected text contains a mix of proofed and un-proofed content, this API returns null.

readonly hasNoProofing: boolean;

Property Value

boolean

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

isActive

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Returns whether the selection in the specified window or pane is active.

readonly isActive: boolean;

Property Value

boolean

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

isColumnSelectModeActive

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Specifies whether column selection mode is active.

isColumnSelectModeActive: boolean;

Property Value

boolean

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

isEndOfRowMark

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Returns whether the selection is at the end-of-row mark in a table.

readonly isEndOfRowMark: boolean;

Property Value

boolean

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

isExtendModeActive

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Specifies whether Extend mode is active.

isExtendModeActive: boolean;

Property Value

boolean

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

isInsertionPointAtEndOfLine

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Returns whether the insertion point is at the end of a line.

readonly isInsertionPointAtEndOfLine: boolean;

Property Value

boolean

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

isStartActive

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Specifies whether the beginning of the selection is active.

isStartActive: boolean;

Property Value

boolean

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

languageDetected

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Specifies whether Word has detected the language of the selected text.

languageDetected: boolean;

Property Value

boolean

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

languageId

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Returns the language for the selection.

readonly languageId: Word.LanguageId | "Afrikaans" | "Albanian" | "Amharic" | "Arabic" | "ArabicAlgeria" | "ArabicBahrain" | "ArabicEgypt" | "ArabicIraq" | "ArabicJordan" | "ArabicKuwait" | "ArabicLebanon" | "ArabicLibya" | "ArabicMorocco" | "ArabicOman" | "ArabicQatar" | "ArabicSyria" | "ArabicTunisia" | "ArabicUAE" | "ArabicYemen" | "Armenian" | "Assamese" | "AzeriCyrillic" | "AzeriLatin" | "Basque" | "BelgianDutch" | "BelgianFrench" | "Bengali" | "Bulgarian" | "Burmese" | "Belarusian" | "Catalan" | "Cherokee" | "ChineseHongKongSAR" | "ChineseMacaoSAR" | "ChineseSingapore" | "Croatian" | "Czech" | "Danish" | "Divehi" | "Dutch" | "Edo" | "EnglishAUS" | "EnglishBelize" | "EnglishCanadian" | "EnglishCaribbean" | "EnglishIndonesia" | "EnglishIreland" | "EnglishJamaica" | "EnglishNewZealand" | "EnglishPhilippines" | "EnglishSouthAfrica" | "EnglishTrinidadTobago" | "EnglishUK" | "EnglishUS" | "EnglishZimbabwe" | "Estonian" | "Faeroese" | "Filipino" | "Finnish" | "French" | "FrenchCameroon" | "FrenchCanadian" | "FrenchCongoDRC" | "FrenchCotedIvoire" | "FrenchHaiti" | "FrenchLuxembourg" | "FrenchMali" | "FrenchMonaco" | "FrenchMorocco" | "FrenchReunion" | "FrenchSenegal" | "FrenchWestIndies" | "FrisianNetherlands" | "Fulfulde" | "GaelicIreland" | "GaelicScotland" | "Galician" | "Georgian" | "German" | "GermanAustria" | "GermanLiechtenstein" | "GermanLuxembourg" | "Greek" | "Guarani" | "Gujarati" | "Hausa" | "Hawaiian" | "Hebrew" | "Hindi" | "Hungarian" | "Ibibio" | "Icelandic" | "Igbo" | "Indonesian" | "Inuktitut" | "Italian" | "Japanese" | "Kannada" | "Kanuri" | "Kashmiri" | "Kazakh" | "Khmer" | "Kirghiz" | "Konkani" | "Korean" | "Kyrgyz" | "LanguageNone" | "Lao" | "Latin" | "Latvian" | "Lithuanian" | "MacedonianFYROM" | "Malayalam" | "MalayBruneiDarussalam" | "Malaysian" | "Maltese" | "Manipuri" | "Marathi" | "MexicanSpanish" | "Mongolian" | "Nepali" | "NoProofing" | "NorwegianBokmol" | "NorwegianNynorsk" | "Oriya" | "Oromo" | "Pashto" | "Persian" | "Polish" | "Portuguese" | "PortugueseBrazil" | "Punjabi" | "RhaetoRomanic" | "Romanian" | "RomanianMoldova" | "Russian" | "RussianMoldova" | "SamiLappish" | "Sanskrit" | "SerbianCyrillic" | "SerbianLatin" | "Sesotho" | "SimplifiedChinese" | "Sindhi" | "SindhiPakistan" | "Sinhalese" | "Slovak" | "Slovenian" | "Somali" | "Sorbian" | "Spanish" | "SpanishArgentina" | "SpanishBolivia" | "SpanishChile" | "SpanishColombia" | "SpanishCostaRica" | "SpanishDominicanRepublic" | "SpanishEcuador" | "SpanishElSalvador" | "SpanishGuatemala" | "SpanishHonduras" | "SpanishModernSort" | "SpanishNicaragua" | "SpanishPanama" | "SpanishParaguay" | "SpanishPeru" | "SpanishPuertoRico" | "SpanishUruguay" | "SpanishVenezuela" | "Sutu" | "Swahili" | "Swedish" | "SwedishFinland" | "SwissFrench" | "SwissGerman" | "SwissItalian" | "Syriac" | "Tajik" | "Tamazight" | "TamazightLatin" | "Tamil" | "Tatar" | "Telugu" | "Thai" | "Tibetan" | "TigrignaEritrea" | "TigrignaEthiopic" | "TraditionalChinese" | "Tsonga" | "Tswana" | "Turkish" | "Turkmen" | "Ukrainian" | "Urdu" | "UzbekCyrillic" | "UzbekLatin" | "Venda" | "Vietnamese" | "Welsh" | "Xhosa" | "Yi" | "Yiddish" | "Yoruba" | "Zulu";

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

languageIdFarEast

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Returns the East Asian language for the selection.

readonly languageIdFarEast: Word.LanguageId | "Afrikaans" | "Albanian" | "Amharic" | "Arabic" | "ArabicAlgeria" | "ArabicBahrain" | "ArabicEgypt" | "ArabicIraq" | "ArabicJordan" | "ArabicKuwait" | "ArabicLebanon" | "ArabicLibya" | "ArabicMorocco" | "ArabicOman" | "ArabicQatar" | "ArabicSyria" | "ArabicTunisia" | "ArabicUAE" | "ArabicYemen" | "Armenian" | "Assamese" | "AzeriCyrillic" | "AzeriLatin" | "Basque" | "BelgianDutch" | "BelgianFrench" | "Bengali" | "Bulgarian" | "Burmese" | "Belarusian" | "Catalan" | "Cherokee" | "ChineseHongKongSAR" | "ChineseMacaoSAR" | "ChineseSingapore" | "Croatian" | "Czech" | "Danish" | "Divehi" | "Dutch" | "Edo" | "EnglishAUS" | "EnglishBelize" | "EnglishCanadian" | "EnglishCaribbean" | "EnglishIndonesia" | "EnglishIreland" | "EnglishJamaica" | "EnglishNewZealand" | "EnglishPhilippines" | "EnglishSouthAfrica" | "EnglishTrinidadTobago" | "EnglishUK" | "EnglishUS" | "EnglishZimbabwe" | "Estonian" | "Faeroese" | "Filipino" | "Finnish" | "French" | "FrenchCameroon" | "FrenchCanadian" | "FrenchCongoDRC" | "FrenchCotedIvoire" | "FrenchHaiti" | "FrenchLuxembourg" | "FrenchMali" | "FrenchMonaco" | "FrenchMorocco" | "FrenchReunion" | "FrenchSenegal" | "FrenchWestIndies" | "FrisianNetherlands" | "Fulfulde" | "GaelicIreland" | "GaelicScotland" | "Galician" | "Georgian" | "German" | "GermanAustria" | "GermanLiechtenstein" | "GermanLuxembourg" | "Greek" | "Guarani" | "Gujarati" | "Hausa" | "Hawaiian" | "Hebrew" | "Hindi" | "Hungarian" | "Ibibio" | "Icelandic" | "Igbo" | "Indonesian" | "Inuktitut" | "Italian" | "Japanese" | "Kannada" | "Kanuri" | "Kashmiri" | "Kazakh" | "Khmer" | "Kirghiz" | "Konkani" | "Korean" | "Kyrgyz" | "LanguageNone" | "Lao" | "Latin" | "Latvian" | "Lithuanian" | "MacedonianFYROM" | "Malayalam" | "MalayBruneiDarussalam" | "Malaysian" | "Maltese" | "Manipuri" | "Marathi" | "MexicanSpanish" | "Mongolian" | "Nepali" | "NoProofing" | "NorwegianBokmol" | "NorwegianNynorsk" | "Oriya" | "Oromo" | "Pashto" | "Persian" | "Polish" | "Portuguese" | "PortugueseBrazil" | "Punjabi" | "RhaetoRomanic" | "Romanian" | "RomanianMoldova" | "Russian" | "RussianMoldova" | "SamiLappish" | "Sanskrit" | "SerbianCyrillic" | "SerbianLatin" | "Sesotho" | "SimplifiedChinese" | "Sindhi" | "SindhiPakistan" | "Sinhalese" | "Slovak" | "Slovenian" | "Somali" | "Sorbian" | "Spanish" | "SpanishArgentina" | "SpanishBolivia" | "SpanishChile" | "SpanishColombia" | "SpanishCostaRica" | "SpanishDominicanRepublic" | "SpanishEcuador" | "SpanishElSalvador" | "SpanishGuatemala" | "SpanishHonduras" | "SpanishModernSort" | "SpanishNicaragua" | "SpanishPanama" | "SpanishParaguay" | "SpanishPeru" | "SpanishPuertoRico" | "SpanishUruguay" | "SpanishVenezuela" | "Sutu" | "Swahili" | "Swedish" | "SwedishFinland" | "SwissFrench" | "SwissGerman" | "SwissItalian" | "Syriac" | "Tajik" | "Tamazight" | "TamazightLatin" | "Tamil" | "Tatar" | "Telugu" | "Thai" | "Tibetan" | "TigrignaEritrea" | "TigrignaEthiopic" | "TraditionalChinese" | "Tsonga" | "Tswana" | "Turkish" | "Turkmen" | "Ukrainian" | "Urdu" | "UzbekCyrillic" | "UzbekLatin" | "Venda" | "Vietnamese" | "Welsh" | "Xhosa" | "Yi" | "Yiddish" | "Yoruba" | "Zulu";

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

languageIdOther

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Returns the language for the selection that isn't classified as an East Asian language.

readonly languageIdOther: Word.LanguageId | "Afrikaans" | "Albanian" | "Amharic" | "Arabic" | "ArabicAlgeria" | "ArabicBahrain" | "ArabicEgypt" | "ArabicIraq" | "ArabicJordan" | "ArabicKuwait" | "ArabicLebanon" | "ArabicLibya" | "ArabicMorocco" | "ArabicOman" | "ArabicQatar" | "ArabicSyria" | "ArabicTunisia" | "ArabicUAE" | "ArabicYemen" | "Armenian" | "Assamese" | "AzeriCyrillic" | "AzeriLatin" | "Basque" | "BelgianDutch" | "BelgianFrench" | "Bengali" | "Bulgarian" | "Burmese" | "Belarusian" | "Catalan" | "Cherokee" | "ChineseHongKongSAR" | "ChineseMacaoSAR" | "ChineseSingapore" | "Croatian" | "Czech" | "Danish" | "Divehi" | "Dutch" | "Edo" | "EnglishAUS" | "EnglishBelize" | "EnglishCanadian" | "EnglishCaribbean" | "EnglishIndonesia" | "EnglishIreland" | "EnglishJamaica" | "EnglishNewZealand" | "EnglishPhilippines" | "EnglishSouthAfrica" | "EnglishTrinidadTobago" | "EnglishUK" | "EnglishUS" | "EnglishZimbabwe" | "Estonian" | "Faeroese" | "Filipino" | "Finnish" | "French" | "FrenchCameroon" | "FrenchCanadian" | "FrenchCongoDRC" | "FrenchCotedIvoire" | "FrenchHaiti" | "FrenchLuxembourg" | "FrenchMali" | "FrenchMonaco" | "FrenchMorocco" | "FrenchReunion" | "FrenchSenegal" | "FrenchWestIndies" | "FrisianNetherlands" | "Fulfulde" | "GaelicIreland" | "GaelicScotland" | "Galician" | "Georgian" | "German" | "GermanAustria" | "GermanLiechtenstein" | "GermanLuxembourg" | "Greek" | "Guarani" | "Gujarati" | "Hausa" | "Hawaiian" | "Hebrew" | "Hindi" | "Hungarian" | "Ibibio" | "Icelandic" | "Igbo" | "Indonesian" | "Inuktitut" | "Italian" | "Japanese" | "Kannada" | "Kanuri" | "Kashmiri" | "Kazakh" | "Khmer" | "Kirghiz" | "Konkani" | "Korean" | "Kyrgyz" | "LanguageNone" | "Lao" | "Latin" | "Latvian" | "Lithuanian" | "MacedonianFYROM" | "Malayalam" | "MalayBruneiDarussalam" | "Malaysian" | "Maltese" | "Manipuri" | "Marathi" | "MexicanSpanish" | "Mongolian" | "Nepali" | "NoProofing" | "NorwegianBokmol" | "NorwegianNynorsk" | "Oriya" | "Oromo" | "Pashto" | "Persian" | "Polish" | "Portuguese" | "PortugueseBrazil" | "Punjabi" | "RhaetoRomanic" | "Romanian" | "RomanianMoldova" | "Russian" | "RussianMoldova" | "SamiLappish" | "Sanskrit" | "SerbianCyrillic" | "SerbianLatin" | "Sesotho" | "SimplifiedChinese" | "Sindhi" | "SindhiPakistan" | "Sinhalese" | "Slovak" | "Slovenian" | "Somali" | "Sorbian" | "Spanish" | "SpanishArgentina" | "SpanishBolivia" | "SpanishChile" | "SpanishColombia" | "SpanishCostaRica" | "SpanishDominicanRepublic" | "SpanishEcuador" | "SpanishElSalvador" | "SpanishGuatemala" | "SpanishHonduras" | "SpanishModernSort" | "SpanishNicaragua" | "SpanishPanama" | "SpanishParaguay" | "SpanishPeru" | "SpanishPuertoRico" | "SpanishUruguay" | "SpanishVenezuela" | "Sutu" | "Swahili" | "Swedish" | "SwedishFinland" | "SwissFrench" | "SwissGerman" | "SwissItalian" | "Syriac" | "Tajik" | "Tamazight" | "TamazightLatin" | "Tamil" | "Tatar" | "Telugu" | "Thai" | "Tibetan" | "TigrignaEritrea" | "TigrignaEthiopic" | "TraditionalChinese" | "Tsonga" | "Tswana" | "Turkish" | "Turkmen" | "Ukrainian" | "Urdu" | "UzbekCyrillic" | "UzbekLatin" | "Venda" | "Vietnamese" | "Welsh" | "Xhosa" | "Yi" | "Yiddish" | "Yoruba" | "Zulu";

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

orientation

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Specifies the orientation of text in the selection.

orientation: Word.TextOrientation | "Horizontal" | "Upward" | "Downward" | "VerticalFarEast" | "HorizontalRotatedFarEast" | "Vertical";

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

paragraphs

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Returns a ParagraphCollection object that represents all the paragraphs in the selection.

readonly paragraphs: Word.ParagraphCollection;

Property Value

Word.ParagraphCollection

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

range

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Returns the Range object for the portion of the document contained in the selection.

readonly range: Word.Range;

Property Value

Word.Range

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

sections

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Returns the SectionCollection object in the selection.

readonly sections: Word.SectionCollection;

Property Value

Word.SectionCollection

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

sentences

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Returns the RangeScopedCollection object for each sentence in the selection.

readonly sentences: Word.RangeScopedCollection;

Property Value

Word.RangeScopedCollection

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

shading

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Returns the ShadingUniversal object for the shading formatting for the selection.

readonly shading: Word.ShadingUniversal;

Property Value

Word.ShadingUniversal

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

start

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Specifies the starting character position of the selection.

start: number;

Property Value

number

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

storyLength

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Returns the number of characters in the story that contains the selection.

readonly storyLength: number;

Property Value

number

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

storyType

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Returns the story type for the selection.

readonly storyType: Word.StoryType | "MainText" | "Footnotes" | "Endnotes" | "Comments" | "TextFrame" | "EvenPagesHeader" | "PrimaryHeader" | "EvenPagesFooter" | "PrimaryFooter" | "FirstPageHeader" | "FirstPageFooter" | "FootnoteSeparator" | "FootnoteContinuationSeparator" | "FootnoteContinuationNotice" | "EndnoteSeparator" | "EndnoteContinuationSeparator" | "EndnoteContinuationNotice";

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

tables

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Returns the TableCollection object in the selection.

readonly tables: Word.TableCollection;

Property Value

Word.TableCollection

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

text

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Specifies the text in the selection.

text: string;

Property Value

string

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

topLevelTables

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Returns the tables at the outermost nesting level in the current selection.

readonly topLevelTables: Word.TableCollection;

Property Value

Word.TableCollection

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

type

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Returns the selection type.

readonly type: Word.SelectionType | "NoSelection" | "InsertionPoint" | "Normal" | "Frame" | "Column" | "Row" | "Block" | "InlineShape" | "SelectionShape";

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

words

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Returns the RangeScopedCollection object that represents each word in the selection.

readonly words: Word.RangeScopedCollection;

Property Value

Word.RangeScopedCollection

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Method Details

calculate()

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Calculates the first mathematical expression within the selection.

calculate(): OfficeExtension.ClientResult<number>;

Returns

OfficeExtension.ClientResult<number>

The result of the calculation.

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

cancelMode()

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Cancels a mode such as extend or column select. This is equivalent to pressing the Esc key.

cancelMode(): void;

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

clearCharacterStyleFormatting()

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Removes character formatting applied through character styles.

clearCharacterStyleFormatting(): void;

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

clearFormatting()

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Removes character and paragraph formatting from the selection.

clearFormatting(): void;

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

clearManualCharacterFormatting()

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Removes manually applied character formatting from the selected text.

clearManualCharacterFormatting(): void;

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

clearManualParagraphFormatting()

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Removes manually applied paragraph formatting from the selected text.

clearManualParagraphFormatting(): void;

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

clearParagraphFormatting()

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Removes all paragraph formatting from the selected text.

clearParagraphFormatting(): void;

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

clearParagraphStyle()

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Removes paragraph formatting applied through paragraph styles.

clearParagraphStyle(): void;

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

collapse(direction)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Collapses the selection to the starting or ending position.

collapse(direction?: Word.CollapseDirection): void;

Parameters

direction: Word.CollapseDirection

Optional. Direction to collapse.

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

collapse(direction)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Collapses the selection to the starting or ending position.

collapse(direction?: "Start" | "End"): void;

Parameters

direction: "Start" | "End"

Optional. Direction to collapse.

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

convertToTable(options)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Converts text within a range to a table.

convertToTable(options?: Word.SelectionConvertToTableOptions): Word.Table;

Parameters

options: Word.SelectionConvertToTableOptions

Optional. Options for converting text to a table.

Returns

Word.Table

A Table object that represents the newly created table.

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

copyAsPictureToClipboard()

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Copies the selection to the Clipboard as a picture.

copyAsPictureToClipboard(): void;

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

copyFormat()

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Copies the character formatting of the first character in the selected text.

copyFormat(): void;

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

copyToClipboard()

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Copies the selection to the Clipboard.

copyToClipboard(): void;

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

createTextBox()

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Adds a default-sized text box around the selection.

createTextBox(): void;

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

cut()

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Removes the selected content from the document and moves it to the Clipboard.

cut(): void;

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

delete(options)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Deletes the specified number of characters or words.

delete(options?: Word.SelectionDeleteOptions): OfficeExtension.ClientResult<number>;

Parameters

options: Word.SelectionDeleteOptions

Optional. Options for deleting text.

Returns

OfficeExtension.ClientResult<number>

The number of characters deleted.

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

detectLanguage()

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Analyzes the selected text to determine the language that it's written in.

detectLanguage(): void;

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

expand(unit)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Expands the selection.

expand(unit?: Word.OperationUnit): OfficeExtension.ClientResult<number>;

Parameters

unit: Word.OperationUnit

Optional. The unit to expand.

Returns

OfficeExtension.ClientResult<number>

The number of characters added to the range or selection.

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

expand(unit)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Expands the selection.

expand(unit?: "Character" | "Word" | "Sentence" | "Paragraph" | "Line" | "Story" | "Screen" | "Section" | "Column" | "Row" | "Window" | "Cell" | "CharacterFormat" | "ParagraphFormat" | "Table" | "Item"): OfficeExtension.ClientResult<number>;

Parameters

unit: "Character" | "Word" | "Sentence" | "Paragraph" | "Line" | "Story" | "Screen" | "Section" | "Column" | "Row" | "Window" | "Cell" | "CharacterFormat" | "ParagraphFormat" | "Table" | "Item"

Optional. The unit to expand.

Returns

OfficeExtension.ClientResult<number>

The number of characters added to the range or selection.

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

expandToWholeStory()

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Expands the selection to include the entire story.

expandToWholeStory(): void;

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

extend(character)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Turns on extend mode, or if extend mode is already on, extends the selection to the next larger unit of text.

extend(character?: Word.OperationUnit): void;

Parameters

character: Word.OperationUnit

Optional. The character through which the selection is extended. This argument is case-sensitive and must evaluate to a string or an error occurs. Also, if the value of this argument is longer than a single character, Microsoft Word ignores the command entirely.

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

extend(character)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Turns on extend mode, or if extend mode is already on, extends the selection to the next larger unit of text.

extend(character?: "Character" | "Word" | "Sentence" | "Paragraph" | "Line" | "Story" | "Screen" | "Section" | "Column" | "Row" | "Window" | "Cell" | "CharacterFormat" | "ParagraphFormat" | "Table" | "Item"): void;

Parameters

character: "Character" | "Word" | "Sentence" | "Paragraph" | "Line" | "Story" | "Screen" | "Section" | "Column" | "Row" | "Window" | "Cell" | "CharacterFormat" | "ParagraphFormat" | "Table" | "Item"

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

getNextRange(options)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Returns a Range object that represents the next unit relative to the selection.

getNextRange(options?: Word.SelectionNextOptions): Word.Range;

Parameters

options: Word.SelectionNextOptions

Optional. Options for the next operation.

Returns

Word.Range

A Range object that represents the next unit relative to the selection.

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

getPreviousRange(options)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Returns a Range object that represents the previous unit relative to the selection.

getPreviousRange(options?: Word.SelectionPreviousOptions): Word.Range;

Parameters

options: Word.SelectionPreviousOptions

Optional. Options for the previous operation.

Returns

Word.Range

A Range object that represents the previous unit relative to the selection.

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

goTo(options)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Returns a Range object that represents the area specified by the options and moves the insertion point to the character position immediately preceding the specified item.

goTo(options?: Word.SelectionGoToOptions): Word.Range;

Parameters

options: Word.SelectionGoToOptions

Optional. Options for the goTo operation.

Returns

Word.Range

A Range object that is now selected.

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

goToNext(what)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Returns a Range object that refers to the start position of the next item or ___location specified by the what argument and moves the selection to the specified item.

goToNext(what: Word.GoToItem): Word.Range;

Parameters

what: Word.GoToItem

The item type to go to.

Returns

Word.Range

A Range object that refers to the start position of the next item or ___location specified by the what argument.

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

goToNext(what)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Returns a Range object that refers to the start position of the next item or ___location specified by the what argument and moves the selection to the specified item.

goToNext(what: "Bookmark" | "Comment" | "Endnote" | "Field" | "Footnote" | "Graphic" | "Heading" | "Line" | "Page" | "Section" | "Table" | "EmbeddedObject" | "Equation" | "Percent" | "SpellingError" | "GrammaticalError" | "ProofreadingError"): Word.Range;

Parameters

what: "Bookmark" | "Comment" | "Endnote" | "Field" | "Footnote" | "Graphic" | "Heading" | "Line" | "Page" | "Section" | "Table" | "EmbeddedObject" | "Equation" | "Percent" | "SpellingError" | "GrammaticalError" | "ProofreadingError"

The item type to go to.

Returns

Word.Range

A Range object that refers to the start position of the next item or ___location specified by the what argument.

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

goToPrevious(what)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Returns a Range object that refers to the start position of the previous item or ___location specified by the what argument and moves the selection to the specified item.

goToPrevious(what: Word.GoToItem): Word.Range;

Parameters

what: Word.GoToItem

The item type to go to.

Returns

Word.Range

A Range object that refers to the start position of the previous item or ___location specified by the what argument.

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

goToPrevious(what)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Returns a Range object that refers to the start position of the previous item or ___location specified by the what argument and moves the selection to the specified item.

goToPrevious(what: "Bookmark" | "Comment" | "Endnote" | "Field" | "Footnote" | "Graphic" | "Heading" | "Line" | "Page" | "Section" | "Table" | "EmbeddedObject" | "Equation" | "Percent" | "SpellingError" | "GrammaticalError" | "ProofreadingError"): Word.Range;

Parameters

what: "Bookmark" | "Comment" | "Endnote" | "Field" | "Footnote" | "Graphic" | "Heading" | "Line" | "Page" | "Section" | "Table" | "EmbeddedObject" | "Equation" | "Percent" | "SpellingError" | "GrammaticalError" | "ProofreadingError"

The item type to go to.

Returns

Word.Range

A Range object that refers to the start position of the previous item or ___location specified by the what argument.

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

insertAfter(text)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Inserts the specified text at the end of the range or selection.

insertAfter(text: string): void;

Parameters

text: string

Text to insert.

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

insertBefore(text)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Inserts the specified text before the selection.

insertBefore(text: string): void;

Parameters

text: string

Text to insert.

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

insertCells(shiftCells)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Adds cells to an existing table.

insertCells(shiftCells?: Word.TableCellInsertionLocation): void;

Parameters

shiftCells: Word.TableCellInsertionLocation

Optional. Specifies how to insert the cells into the existing columns and rows of the table. The default value is shiftDown.

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

insertCells(shiftCells)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Adds cells to an existing table.

insertCells(shiftCells?: "ShiftRight" | "ShiftDown" | "ShiftRowDown" | "ShiftColumnRight"): void;

Parameters

shiftCells: "ShiftRight" | "ShiftDown" | "ShiftRowDown" | "ShiftColumnRight"

insertDateTime(options?: Word.SelectionInsertDateTimeOptions): void;

Parameters

options: Word.SelectionInsertDateTimeOptions

Options for inserting the date or time.

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

insertFormula(options)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Inserts a Formula field at the selection.

insertFormula(options?: Word.SelectionInsertFormulaOptions): void;

Parameters

options: Word.SelectionInsertFormulaOptions

insertRowsAbove(numRows: number): void;

Parameters

numRows: number

Optional. Number of rows to insert.

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

insertRowsBelow(numRows)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Inserts rows below the current selection.

insertRowsBelow(numRows: number): void;

Parameters

numRows: number

Optional. Number of rows to insert.

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

insertSymbol(characterNumber, options)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Inserts a symbol in place of the specified selection.

insertSymbol(characterNumber: number, options?: Word.SelectionInsertSymbolOptions): void;

Parameters

characterNumber: number

The character number of the symbol.

options: Word.SelectionInsertSymbolOptions

Optional. Options for inserting the symbol.

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

insertText(Text)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Inserts the specified text.

insertText(Text: string): void;

Parameters

Text: string

The text to insert.

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

insertXml(xml, transform)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Inserts the specified XML into the document at the cursor, replacing any selected text.

insertXml(xml: string, transform?: string): void;

Parameters

xml: string

The XML string to insert.

transform: string

Optional. XSL transform to apply.

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

isEqual(range)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Returns whether the selection is equal to the specified range.

isEqual(range: Word.Range): OfficeExtension.ClientResult<boolean>;

Parameters

range: Word.Range

The range to compare.

Returns

OfficeExtension.ClientResult<boolean>

true if the selection is equal to the specified range.

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

isInRange(range)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Returns true if the selection is contained within the specified range.

isInRange(range: Word.Range): OfficeExtension.ClientResult<boolean>;

Parameters

range: Word.Range

The range to compare.

Returns

OfficeExtension.ClientResult<boolean>

true if the selection is contained within the specified range.

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

isInStory(range)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Returns whether the selection is in the same story as the specified range.

isInStory(range: Word.Range): OfficeExtension.ClientResult<boolean>;

Parameters

range: Word.Range

The range to compare.

Returns

OfficeExtension.ClientResult<boolean>

true if the selection is in the same story as the specified range.

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

load(options)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

load(options?: Word.Interfaces.SelectionLoadOptions): Word.Selection;

Parameters

options: Word.Interfaces.SelectionLoadOptions

Provides options for which properties of the object to load.

Returns

Word.Selection

load(propertyNames)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

load(propertyNames?: string | string[]): Word.Selection;

Parameters

propertyNames: string | string[]

A comma-delimited string or an array of strings that specify the properties to load.

Returns

Word.Selection

load(propertyNamesAndPaths)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

load(propertyNamesAndPaths?: {
            select?: string;
            expand?: string;
        }): Word.Selection;

Parameters

propertyNamesAndPaths: { select?: string; expand?: string; }

propertyNamesAndPaths.select is a comma-delimited string that specifies the properties to load, and propertyNamesAndPaths.expand is a comma-delimited string that specifies the navigation properties to load.

Returns

Word.Selection

move(options)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Collapses the selection to its start or end position and then moves the collapsed object by the specified number of units.

move(options?: Word.SelectionMoveOptions): OfficeExtension.ClientResult<number>;

Parameters

options: Word.SelectionMoveOptions

Optional. Options for moving the selection.

Returns

OfficeExtension.ClientResult<number>

The number of characters by which the selection was moved.

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

moveDown(options)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Moves the selection down.

moveDown(options?: Word.SelectionMoveUpDownOptions): OfficeExtension.ClientResult<number>;

Parameters

options: Word.SelectionMoveUpDownOptions

Optional. Options for moving down.

Returns

OfficeExtension.ClientResult<number>

The number of characters by which the selection was moved.

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

moveEnd(options)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Moves the ending character position of the range or selection.

moveEnd(options?: Word.SelectionMoveStartEndOptions): OfficeExtension.ClientResult<number>;

Parameters

options: Word.SelectionMoveStartEndOptions

Optional. Options for moving end.

Returns

OfficeExtension.ClientResult<number>

The number of characters by which the selection was moved.

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

moveEndUntil(characters, count)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Moves the end position of the selection until any of the specified characters are found in the document.

moveEndUntil(characters: string, count?: number): OfficeExtension.ClientResult<number>;

Parameters

characters: string

Characters to search for. For example. If you specify "a", the selection moves the end position to before the first "a" character.

count: number

Optional. Maximum number of characters to search.

Returns

OfficeExtension.ClientResult<number>

The number of characters by which the selection was moved.

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

moveEndWhile(characters, count)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Moves the ending character position of the selection while any of the specified characters are found in the document.

moveEndWhile(characters: string, count?: number): OfficeExtension.ClientResult<number>;

Parameters

characters: string

Characters to search for. For example. If you specify "abcd", the selection moves the end position when any letter from "abcd" is found.

count: number

Optional. Maximum number of characters to search.

Returns

OfficeExtension.ClientResult<number>

The number of characters by which the selection was moved.

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

moveLeft(options)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Moves the selection to the left.

moveLeft(options?: Word.SelectionMoveLeftRightOptions): OfficeExtension.ClientResult<number>;

Parameters

options: Word.SelectionMoveLeftRightOptions

Optional. Options for moving left.

Returns

OfficeExtension.ClientResult<number>

The number of characters by which the selection was moved.

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

moveRight(options)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Moves the selection to the right.

moveRight(options?: Word.SelectionMoveLeftRightOptions): OfficeExtension.ClientResult<number>;

Parameters

options: Word.SelectionMoveLeftRightOptions

Optional. Options for moving right.

Returns

OfficeExtension.ClientResult<number>

The number of characters by which the selection was moved.

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

moveStart(options)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Moves the start position of the selection.

moveStart(options?: Word.SelectionMoveStartEndOptions): OfficeExtension.ClientResult<number>;

Parameters

options: Word.SelectionMoveStartEndOptions

Optional. Options for the moveStart operation.

Returns

OfficeExtension.ClientResult<number>

The number of characters by which the selection was moved.

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

moveStartUntil(characters, count)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Moves the start position of the selection until one of the specified characters is found in the document.

moveStartUntil(characters: string, count?: number): OfficeExtension.ClientResult<number>;

Parameters

characters: string

Characters to search for. If you specify "a", the selection moves the start position to before the first "a" character.

count: number

Optional. Maximum number of characters to search.

Returns

OfficeExtension.ClientResult<number>

The number of characters by which the selection was moved.

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

moveStartWhile(characters, count)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Moves the start position of the selection while any of the specified characters are found in the document.

moveStartWhile(characters: string, count?: number): OfficeExtension.ClientResult<number>;

Parameters

characters: string

Characters to search for. For example. If you specify "abcd", the selection moves the start position when any letter from "abcd" is found.

count: number

Optional. Maximum number of characters to search.

Returns

OfficeExtension.ClientResult<number>

The number of characters by which the selection was moved.

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

moveUntil(characters, count)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Moves the selection until one of the specified characters is found in the document.

moveUntil(characters: string, count?: number): OfficeExtension.ClientResult<number>;

Parameters

characters: string

Characters to search for. For example. If you specify "a", the selection moves to the position before the first "a" character.

count: number

Optional. Maximum number of characters to search.

Returns

OfficeExtension.ClientResult<number>

The number of characters by which the selection was moved.

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

moveUp(options)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Moves the selection up.

moveUp(options?: Word.SelectionMoveUpDownOptions): OfficeExtension.ClientResult<number>;

Parameters

options: Word.SelectionMoveUpDownOptions

Optional. Options for moving up.

Returns

OfficeExtension.ClientResult<number>

The number of characters by which the selection was moved.

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

moveWhile(characters, count)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Moves the selection while any of the specified characters are found in the document.

moveWhile(characters: string, count?: number): OfficeExtension.ClientResult<number>;

Parameters

characters: string

Characters to search for. For example. If you specify "abcd", the selection moves to the position when any letter from "abcd" is found.

count: number

Optional. Maximum number of characters to search.

Returns

OfficeExtension.ClientResult<number>

The number of characters by which the selection was moved.

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

nextField()

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Selects the next field.

nextField(): Word.Field;

Returns

Word.Field

The next field.

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

nextSubdocument()

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Moves the selection to the next subDocument.

nextSubdocument(): void;

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

pasteAndFormat(type)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Pastes the content from clipboard and formats them as specified.

pasteAndFormat(type: Word.PasteFormatType): void;

Parameters

type: Word.PasteFormatType

The format paste type for table cells

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

pasteAndFormat(type)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Pastes the content from clipboard and formats them as specified.

pasteAndFormat(type: "PasteDefault" | "SingleCellText" | "SingleCellTable" | "ListContinueNumbering" | "ListRestartNumbering" | "TableAppendTable" | "TableInsertAsRows" | "TableOriginalFormatting" | "ChartPicture" | "Chart" | "ChartLinked" | "FormatOriginalFormatting" | "FormatSurroundingFormattingWithEmphasis" | "FormatPlainText" | "TableOverwriteCells" | "ListCombineWithExistingList" | "ListDontMerge" | "UseDestinationStylesRecovery"): void;

Parameters

type: "PasteDefault" | "SingleCellText" | "SingleCellTable" | "ListContinueNumbering" | "ListRestartNumbering" | "TableAppendTable" | "TableInsertAsRows" | "TableOriginalFormatting" | "ChartPicture" | "Chart" | "ChartLinked" | "FormatOriginalFormatting" | "FormatSurroundingFormattingWithEmphasis" | "FormatPlainText" | "TableOverwriteCells" | "ListCombineWithExistingList" | "ListDontMerge" | "UseDestinationStylesRecovery"

The format paste type for table cells

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

pasteExcelTable(linkedToExcel, wordFormatting, rtf)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Pastes and formats a Microsoft Excel table.

pasteExcelTable(linkedToExcel: boolean, wordFormatting: boolean, rtf: boolean): void;

Parameters

linkedToExcel: boolean

Whether the table is linked to Excel.

wordFormatting: boolean

Whether to apply Word formatting.

rtf: boolean

previousField(): Word.Field;

Returns

Word.Field

The previous field.

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

previousSubdocument()

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Moves the selection to the previous subDocument.

previousSubdocument(): void;

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

replaceParagraph()

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Replaces the selection with a new paragraph.

replaceParagraph(): void;

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

select()

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Selects the current text.

select(): void;

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

selectCell()

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Selects the entire cell containing the current selection when the selection is in a table.

selectCell(): void;

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

selectColumn()

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Selects the column that contains the insertion point, or selects all columns that contain the selection when the selection is in a table.

selectColumn(): void;

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

selectCurrentAlignment()

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Extends the selection forward until text with a different paragraph alignment is encountered.

selectCurrentAlignment(): void;

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

selectCurrentColor()

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Extends the selection forward until text with a different color is encountered.

selectCurrentColor(): void;

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

selectCurrentFont()

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Extends the selection forward until text in a different font or font size is encountered.

selectCurrentFont(): void;

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

selectCurrentIndent()

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Extends the selection forward until text with different left or right paragraph indents is encountered.

selectCurrentIndent(): void;

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

selectCurrentSpacing()

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Extends the selection forward until a paragraph with different line spacing is encountered.

selectCurrentSpacing(): void;

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

selectCurrentTabs()

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Extends the selection forward until a paragraph with different tab stops is encountered.

selectCurrentTabs(): void;

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

selectRow()

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Selects the row that contains the insertion point, or selects all rows that contain the selection when the selection is in a table.

selectRow(): void;

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

setRange(start, end)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Sets the starting and ending character positions for the selection. Character position values start at the beginning of the story, with the first value being 0. All characters are counted, including nonprinting characters. Hidden characters are counted even if they're not displayed.

setRange(start: number, end: number): void;

Parameters

start: number

The starting character position of the current story.

end: number

toJSON(): Word.Interfaces.SelectionData;

Returns

Word.Interfaces.SelectionData

track()

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

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. If this object is part of a collection, you should also track the parent collection.

track(): Word.Selection;

Returns

Word.Selection

typeBackspace()

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Deletes the character preceding the selection (if collapsed) or the insertion point.

typeBackspace(): void;

Returns

void

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

untrack()

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

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.

untrack(): Word.Selection;

Returns

Word.Selection

Feedback

Was this page helpful?

Share via

Word.Selection class

Remarks

Properties

Methods

Property Details

borders

Property Value

Remarks

characters

Property Value

Remarks

comments

Property Value

Remarks

context

Property Value

end

Property Value

Remarks

fields

Property Value

Remarks

fitTextWidth

Property Value

Remarks

font

Property Value

Remarks

formattedText

Property Value

Remarks

hasNoProofing

Property Value

Remarks

isActive

Property Value

Remarks

isColumnSelectModeActive

Property Value

Remarks

isEndOfRowMark

Property Value

Remarks

isExtendModeActive

Property Value

Remarks

isInsertionPointAtEndOfLine

Property Value

Remarks

isStartActive

Property Value

Remarks

languageDetected

Property Value

Remarks

languageId

Property Value

Remarks

languageIdFarEast

Property Value

Remarks

languageIdOther

Property Value

Remarks

orientation

Property Value

Remarks

paragraphs

Property Value

Remarks

range

Property Value

Remarks

sections

Property Value

Remarks

sentences

Property Value

Remarks