Class TextFinder
Page Summary
TextFinder is used to find or replace text within a range, sheet, or spreadsheet with customizable search options.
Key methods include finding all matches, navigating through matches, getting the current match, and replacing text.
Search behavior can be configured to ignore diacritics, match case, match entire cells, or search within formulas.
TextFinder allows starting a search from a specific range and supports using regular expressions.
Find or replace text within a range, sheet or spreadsheet. Can also specify search options.
Methods
| Method | Return type | Brief description |
|---|---|---|
find | Range[] | Returns all cells matching the search criteria. |
find | Range | Returns the next cell matching the search criteria. |
find | Range | Returns the previous cell matching the search criteria. |
get | Range | Returns the current cell matching the search criteria. |
ignore | Text | Iftrue, configures the search to ignore diacritics while matching; otherwise thesearch matches diacritics. |
match | Text | Iftrue, configures the search to match the search text's case exactly, otherwise thesearch defaults to case-insensitive matching. |
match | Text | Iftrue, configures the search to match the entire contents of a cell; otherwise, thesearch defaults to partial matching. |
match | Text | Iftrue, configures the search to return matches that appear within formula text;otherwise cells with formulas are considered based on their displayed value. |
replace | Integer | Replaces all matches with the specified text. |
replace | Integer | Replaces the search text in the currently matched cell with the specified text and returns thenumber of occurrences replaced. |
start | Text | Configures the search to start searching immediately after the specified cell range. |
use | Text | Iftrue, configures the search to interpret the search string as a regular expression;otherwise the search interprets the search string as normal text. |
Detailed documentation
findAll()
findNext()
Returns the next cell matching the search criteria.
Return
Range — The next matching cell, ornull if there are no previous matches.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/spreadsheets.currentonlyhttps://www.googleapis.com/auth/spreadsheets
findPrevious()
Returns the previous cell matching the search criteria.
Return
Range — The previous matching cell, ornull if there are no previous matches.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/spreadsheets.currentonlyhttps://www.googleapis.com/auth/spreadsheets
getCurrentMatch()
Returns the current cell matching the search criteria.
Return
Range — The current matching cell, ornull if there are no further matches.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/spreadsheets.currentonlyhttps://www.googleapis.com/auth/spreadsheets
ignoreDiacritics(ignoreDiacritics)
Iftrue, configures the search to ignore diacritics while matching; otherwise thesearch matches diacritics. A diacritic is a sign, such as an accent or cedilla, which whenwritten above or below a letter indicates a difference in pronunciation from the same letterwhen unmarked or differently marked.
Parameters
| Name | Type | Description |
|---|---|---|
ignore | Boolean | Whether the search considers diacritics. |
Return
Text — This text finder, for chaining.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/spreadsheets.currentonlyhttps://www.googleapis.com/auth/spreadsheets
matchCase(matchCase)
Iftrue, configures the search to match the search text's case exactly, otherwise thesearch defaults to case-insensitive matching.
Parameters
| Name | Type | Description |
|---|---|---|
match | Boolean | Whether the matching is case-sensitive. |
Return
Text — This text finder, for chaining.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/spreadsheets.currentonlyhttps://www.googleapis.com/auth/spreadsheets
matchEntireCell(matchEntireCell)
Iftrue, configures the search to match the entire contents of a cell; otherwise, thesearch defaults to partial matching.
Parameters
| Name | Type | Description |
|---|---|---|
match | Boolean | Whether the entire cell is matched. |
Return
Text — This text finder, for chaining.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/spreadsheets.currentonlyhttps://www.googleapis.com/auth/spreadsheets
matchFormulaText(matchFormulaText)
Iftrue, configures the search to return matches that appear within formula text;otherwise cells with formulas are considered based on their displayed value.
Parameters
| Name | Type | Description |
|---|---|---|
match | Boolean | Whether the search examines formula text. |
Return
Text — This text finder, for chaining.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/spreadsheets.currentonlyhttps://www.googleapis.com/auth/spreadsheets
replaceAllWith(replaceText)
Replaces all matches with the specified text. Returns the number of occurrences replaced, whichmay be different from the number of matched cells.
Parameters
| Name | Type | Description |
|---|---|---|
replace | String | The text that replaces the text in the matched cells. |
Return
Integer — The number of occurrences replaced.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/spreadsheets.currentonlyhttps://www.googleapis.com/auth/spreadsheets
replaceWith(replaceText)
Replaces the search text in the currently matched cell with the specified text and returns thenumber of occurrences replaced.
Parameters
| Name | Type | Description |
|---|---|---|
replace | String | The text that replaces the content in the currently matched cell. |
Return
Integer — The number of occurrences replaced.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/spreadsheets.currentonlyhttps://www.googleapis.com/auth/spreadsheets
startFrom(startRange)
Configures the search to start searching immediately after the specified cell range.
Parameters
| Name | Type | Description |
|---|---|---|
start | Range | The cell range after which the search should start. |
Return
Text — This text finder, for chaining.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/spreadsheets.currentonlyhttps://www.googleapis.com/auth/spreadsheets
useRegularExpression(useRegEx)
Iftrue, configures the search to interpret the search string as a regular expression;otherwise the search interprets the search string as normal text. For more details on how touse regular expressions, refer to theFind and replace support page.
Parameters
| Name | Type | Description |
|---|---|---|
use | Boolean | Whether to interpret the search string as a regular expression. |
Return
Text — This text finder, for chaining.
Authorization
Scripts that use this method require authorization with one or more of the followingscopes:
https://www.googleapis.com/auth/spreadsheets.currentonlyhttps://www.googleapis.com/auth/spreadsheets
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.