Class TextRange
Page Summary
A TextRange is a segment of text within a Shape or TableCell.
Using methods that edit how text fits within a shape will deactivate any autofit settings applied to that shape.
TextRange provides various methods for manipulating text, including appending, clearing, finding, getting information about, inserting, replacing, selecting, and setting text content.
Methods like
asRenderedString()andasString()allow retrieving the text in different formats, including rendered text and raw text with special characters for non-text elements.Several methods require specific authorization scopes, such as
https://www.googleapis.com/auth/presentations.currentonlyorhttps://www.googleapis.com/auth/presentations.
A segment of the text contents of aShape or aTable.
If you use methods that edit how the text fits within a shape, any autofit settings applied tothe shape are deactivated.
Methods
| Method | Return type | Brief description |
|---|---|---|
append | Paragraph | Appends a paragraph at the end of the text range. |
append | Text | Appends a copy of the provided text range to the end of the current text range. |
append | Text | Appends a copy of the provided text range to the end of the current text range. |
append | Text | Appends text at the end of the text range. |
as | String | Returns the rendered text bounded by this range of the associated shape or table cell in aformat appropriate to display to end users. |
as | String | Returns the raw text bounded by this range of the associated shape or table cell. |
clear() | void | Clears the text bounded by this range. |
clear(startOffset, endOffset) | void | Clears the text bounded by the start and end offsets in the range. |
find(pattern) | Text | Returns all the ranges matching the search pattern in the current text range. |
find(pattern, startOffset) | Text | Returns all the ranges matching the search pattern in the current text range starting from thestart offset. |
get | Auto | Returns the auto texts within the current text range. |
get | Integer | Returns the exclusive, 0-based index for the last character in this range. |
get | Integer | Returns the number of characters in this range. |
get | Text | Returns a collection of text ranges that correspond to allLinks within the currenttext range or overlapping the current text range. |
get | Paragraph[] | Returns the paragraphs in lists that overlap the current text range. |
get | List | Returns theList of the current text range. |
get | Paragraph | Returns theParagraph of the current text range. |
get | Paragraph[] | Returns the paragraphs that overlap the current text range. |
get | Text | Returns a newText covering part of the range from which it is derived. |
get | Text | Returns the text runs that overlap the current text range. |
get | Integer | Returns the inclusive, 0-based index for the first character in this range. |
get | Text | Returns the text style of the range, ornull if the range is empty. |
insert | Paragraph | Inserts a paragraph at the start offset. |
insert | Text | Inserts a copy of the provided text range at the start offset. |
insert | Text | Inserts a copy of the provided text range at the start offset. |
insert | Text | Inserts text at the start offset. |
is | Boolean | Returnstrue if there are no characters in this range, and returnsfalseotherwise. |
replace | Integer | Replaces all instances of text matching find text with replace text. |
replace | Integer | Replaces all instances of text matching find text with replace text. |
select() | void | Selects only theText in the active presentation and removes any previousselection. |
set | Text | Sets the text bounded by this range of the associated shape or table cell. |
Detailed documentation
appendParagraph(text)
Appends a paragraph at the end of the text range. The paragraph maintains the styling of theend of the current text range.
The provided text string is appended as a paragraph by adding at least one surroundingnewline character to the string.
When the provided text string contains newline characters (thus consisting of multipleparagraphs), the final paragraph added is returned.
Parameters
| Name | Type | Description |
|---|---|---|
text | String | The string to append as a paragraph. |
Return
Paragraph — The appendedParagraph.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/presentations.currentonlyhttps://www.googleapis.com/auth/presentations
appendRange(textRange)
Appends a copy of the provided text range to the end of the current text range.
The formatting of the inserted text matches that of the source text.
Parameters
| Name | Type | Description |
|---|---|---|
text | Text | The text range to append. |
Return
Text — The text range representing the appended text.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/presentations.currentonlyhttps://www.googleapis.com/auth/presentations
appendRange(textRange, matchSourceFormatting)
Appends a copy of the provided text range to the end of the current text range.
If set to match the formatting of the destination text,Auto within the providedtext range are replaced with their rendered values. Furthermore, any non-text elements withinthe provided text range are not appended.
Parameters
| Name | Type | Description |
|---|---|---|
text | Text | The text range to append. |
match | Boolean | Iftrue, match the formatting of the source text; iffalse, match the formatting of the destination text. |
Return
Text — The text range representing the appended text.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/presentations.currentonlyhttps://www.googleapis.com/auth/presentations
appendText(text)
Appends text at the end of the text range. The text maintains the styling of the end of theexisting text.
Parameters
| Name | Type | Description |
|---|---|---|
text | String | The string to append. |
Return
Text — The text range representing the appended text.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/presentations.currentonlyhttps://www.googleapis.com/auth/presentations
asRenderedString()
Returns the rendered text bounded by this range of the associated shape or table cell in aformat appropriate to display to end users.
Auto
Return
String — The rendered text in the range.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/presentations.currentonlyhttps://www.googleapis.com/auth/presentations
asString()
Returns the raw text bounded by this range of the associated shape or table cell.
Auto
Return
String — The raw text in the range.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/presentations.currentonlyhttps://www.googleapis.com/auth/presentations
clear()
Clears the text bounded by this range.
Since the entire text in a Shape or TableCell must end in a newline, the final newline inthe text is not removed.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/presentations.currentonlyhttps://www.googleapis.com/auth/presentations
clear(startOffset, endOffset)
Clears the text bounded by the start and end offsets in the range.
Since the text must end in a newline, the final newline in text is not removed even if it'scovered by the given offsets.
Parameters
| Name | Type | Description |
|---|---|---|
start | Integer | The number of characters past the start index of the current text range used to determine the inclusive start index of the range to clear. The start offset must be equal to or greater than 0 and less than or equal toend.start must also be less than the length of the current range. |
end | Integer | The number of characters past the start index of the current text range used to determine the exclusive end index of the range to clear. Theend must be equal to or greater thanstart.end must also be less than or equal to the length of the current range. |
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/presentations.currentonlyhttps://www.googleapis.com/auth/presentations
find(pattern)
Returns all the ranges matching the search pattern in the current text range. The search iscase sensitive.
Parameters
| Name | Type | Description |
|---|---|---|
pattern | String | The regular expression pattern to search; any backslashes in the pattern should be escaped. |
Return
Text — A list of text ranges.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/presentations.currentonlyhttps://www.googleapis.com/auth/presentations
find(pattern, startOffset)
Returns all the ranges matching the search pattern in the current text range starting from thestart offset. The search is case sensitive.
Parameters
| Name | Type | Description |
|---|---|---|
pattern | String | The regular expression pattern to search; any backslashes in the pattern should be escaped. |
start | Integer | The number of characters past the start index of the current text range used to determine the inclusive start index of the range to search.start must also be less than the length of the current range. |
Return
Text — A list of text ranges.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/presentations.currentonlyhttps://www.googleapis.com/auth/presentations
getAutoTexts()
Returns the auto texts within the current text range.
Return
Auto — A list of auto texts.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/presentations.currentonlyhttps://www.googleapis.com/auth/presentations
getEndIndex()
Returns the exclusive, 0-based index for the last character in this range. If the start and endindices are equal, the range is considered to be empty.
Return
Integer — The end index of the range.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/presentations.currentonlyhttps://www.googleapis.com/auth/presentations
getLength()
Returns the number of characters in this range.
Return
Integer — The number of characters in this range.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/presentations.currentonlyhttps://www.googleapis.com/auth/presentations
getLinks()
Returns a collection of text ranges that correspond to allLinks within the currenttext range or overlapping the current text range.
Each returned range is guaranteed to span one link when it is created. Text modificationscan cause it to no longer represent exactly one link.
EachLink on the returned ranges can be accessed viaText.
// Accesses the first link on a TextRange object.consttextRange=SlidesApp.getActivePresentation().getSlides()[0].getShapes()[0].getText();constlinkTextRange=textRange.getLinks()[0];consttextStyle=linkTextRange.getTextStyle();Logger.log(textStyle.hasLink());// logs 'true'constlink=textStyle.getLink();// Link object
Return
Text — A list of text ranges.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/presentations.currentonlyhttps://www.googleapis.com/auth/presentations
getListParagraphs()
Returns the paragraphs in lists that overlap the current text range.
Return
Paragraph[] — A list of paragraphs in lists.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/presentations.currentonlyhttps://www.googleapis.com/auth/presentations
getListStyle()
Returns theList of the current text range.
Return
List — The list style of the current text range.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/presentations.currentonlyhttps://www.googleapis.com/auth/presentations
getParagraphStyle()
Returns theParagraph of the current text range.
Return
Paragraph — The paragraph style of the current text range.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/presentations.currentonlyhttps://www.googleapis.com/auth/presentations
getParagraphs()
Returns the paragraphs that overlap the current text range.
Return
Paragraph[] — A list of paragraphs.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/presentations.currentonlyhttps://www.googleapis.com/auth/presentations
getRange(startOffset, endOffset)
Returns a newText covering part of the range from which it is derived.
Parameters
| Name | Type | Description |
|---|---|---|
start | Integer | The number of characters past the start index of the current text range used to determine the inclusive start index of the returned range. The start offset must be equal to or greater than 0 and less than or equal toend.start must also be less than the length of the current range. |
end | Integer | The number of characters past the start index of the current text range used to determine the exclusive end index of the returned range. Theend must be equal to or greater thanstart.end must also be less than or equal to the length of the current range. |
Return
Text — A new text range.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/presentations.currentonlyhttps://www.googleapis.com/auth/presentations
getRuns()
Returns the text runs that overlap the current text range. A text run is a segment of textwhere all the characters have the same text style.
Each returned range is only guaranteed to span one run when it is created. Text or stylemodifications can cause it to no longer represent exactly one run.
Return
Text — A list of text ranges.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/presentations.currentonlyhttps://www.googleapis.com/auth/presentations
getStartIndex()
Returns the inclusive, 0-based index for the first character in this range. If the start andend indices are equal, the range is considered to be empty.
Return
Integer — The start index of the range.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/presentations.currentonlyhttps://www.googleapis.com/auth/presentations
getTextStyle()
Returns the text style of the range, ornull if the range is empty.
Return
Text — The text style of the range.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/presentations.currentonlyhttps://www.googleapis.com/auth/presentations
insertParagraph(startOffset, text)
Inserts a paragraph at the start offset. The paragraph maintains the styling of the currenttext range at the start offset.
The provided text string is inserted as a paragraph by adding at least one surroundingnewline character to the string.
When the provided text string contains newline characters (thus consisting of multipleparagraphs), the final paragraph added is returned.
Parameters
| Name | Type | Description |
|---|---|---|
start | Integer | The number of characters past the start index of the current text range used to determine the inclusive start index of the text to insert. |
text | String | The string to insert. |
Return
Paragraph — The insertedParagraph.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/presentations.currentonlyhttps://www.googleapis.com/auth/presentations
insertRange(startOffset, textRange)
Inserts a copy of the provided text range at the start offset.
The formatting of the inserted text matches that of the source text.
Parameters
| Name | Type | Description |
|---|---|---|
start | Integer | The number of characters past the start index of the current text range used to determine the inclusive start index of the text to insert. |
text | Text | The text range to insert. |
Return
Text — The text range representing the inserted text.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/presentations.currentonlyhttps://www.googleapis.com/auth/presentations
insertRange(startOffset, textRange, matchSourceFormatting)
Inserts a copy of the provided text range at the start offset.
If set to match the formatting of the destination text,Auto within the providedtext range are replaced with their rendered values. Furthermore, any non-text elements withinthe provided text range are not inserted.
Parameters
| Name | Type | Description |
|---|---|---|
start | Integer | The number of characters past the start index of the current text range used to determine the inclusive start index of the text to insert. |
text | Text | The text range to insert. |
match | Boolean | Iftrue, match the formatting of the source text; iffalse, match the formatting of the destination text. |
Return
Text — The text range representing the inserted text.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/presentations.currentonlyhttps://www.googleapis.com/auth/presentations
insertText(startOffset, text)
Inserts text at the start offset. The text maintains the styling of the existing text at thestart offset.
Parameters
| Name | Type | Description |
|---|---|---|
start | Integer | The number of characters past the start index of the current text range used to determine the inclusive start index of the text to insert. |
text | String | The string to insert. |
Return
Text — The text range representing the inserted text.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/presentations.currentonlyhttps://www.googleapis.com/auth/presentations
isEmpty()
Returnstrue if there are no characters in this range, and returnsfalseotherwise.
Return
Boolean —true if there are no characters in this range, and returnsfalse otherwise.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/presentations.currentonlyhttps://www.googleapis.com/auth/presentations
replaceAllText(findText, replaceText)
Replaces all instances of text matching find text with replace text. The search is caseinsensitive.
Parameters
| Name | Type | Description |
|---|---|---|
find | String | The text to find. |
replace | String | The text to replace the matched text. |
Return
Integer — the number of occurrences changed
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/presentations.currentonlyhttps://www.googleapis.com/auth/presentations
replaceAllText(findText, replaceText, matchCase)
Replaces all instances of text matching find text with replace text.
Parameters
| Name | Type | Description |
|---|---|---|
find | String | The text to find. |
replace | String | The text to replace the matched text. |
match | Boolean | Iftrue, the search is case sensitive; iffalse, the search is case insensitive. |
Return
Integer — the number of occurrences changed
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/presentations.currentonlyhttps://www.googleapis.com/auth/presentations
select()
Selects only theText in the active presentation and removes any previousselection.
A script can only access the selection of the user who is running the script, and only ifthe script isbound to the presentation.
The parentPage of the correspondingShape or theTable is setas thecurrent page selection. TheShape or theTable is set as theselected page element.
Selection can be of two types:- 1. Range of text, use select on a non-empty TextRange to select the range of the characters.
- 2. Cursor position, use an empty TextRange to place the cursor at the desired index.
constshape=SlidesApp.getActivePresentation().getSlides()[0].getShapes()[0];shape.getText().setText('Hello');// Range selection: Select the text range "He".shape.getText().getRange(0,2).select();// Cursor selection: Place the cursor after "H" like "H|ello".shape.getText().getRange(1,1).select();
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/presentations.currentonlyhttps://www.googleapis.com/auth/presentations
setText(newText)
Sets the text bounded by this range of the associated shape or table cell. The text maintainsthe styling of the start of the existing text.
Parameters
| Name | Type | Description |
|---|---|---|
new | String | The string to set as the new text. |
Return
Text — The text range representing the set text.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/presentations.currentonlyhttps://www.googleapis.com/auth/presentations
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-12-11 UTC.