Class Selection
Page Summary
A selection is the set of cells the user has highlighted in the sheet, which can include non-adjacent ranges.
The current cell within a selection is where the user's focus is, highlighted with a darker border in the Google Sheets UI.
The
Selectionobject provides methods to access the active range, list of active ranges, the active sheet, and the current cell.Methods like
getActiveRange(),getActiveRangeList(),getActiveSheet(), andgetCurrentCell()allow programmatic interaction with the user's selection.The
getNextDataRange()method helps find the next data region edge based on the current cell and active range.
Access the current active selection in the active sheet. A selection is the set of cells the userhas highlighted in the sheet, which can be non-adjacent ranges. One cell in the selection is thecurrent cell, where the user's current focus is. The current cell is highlighted with adarker border in the Google Sheets UI.
constactiveSheet=SpreadsheetApp.getActiveSheet();constrangeList=activeSheet.getRangeList(['A1:B4','D1:E4']);rangeList.activate();constselection=activeSheet.getSelection();// Current Cell: D1console.log(`Current Cell:${selection.getCurrentCell().getA1Notation()}`);// Active Range: D1:E4console.log(`Active Range:${selection.getActiveRange().getA1Notation()}`);// Active Ranges: A1:B4, D1:E4constranges=selection.getActiveRangeList().getRanges();for(leti=0;i <ranges.length;i++){console.log(`Active Ranges:${ranges[i].getA1Notation()}`);}console.log(`Active Sheet:${selection.getActiveSheet().getName()}`);
Methods
| Method | Return type | Brief description |
|---|---|---|
get | Range|null | Returns the selected range in the active sheet, ornull if there is no active range. |
get | Range | Returns the list of active ranges in the active sheet ornull if there are no activeranges. |
get | Sheet | Returns the active sheet in the spreadsheet. |
get | Range|null | Returns the current (highlighted) cell that is selected in one of the active ranges ornull if there is no current cell. |
get | Range|null | Starting from thecurrent cell andactive rangeand moving in the given direction, returns an adjusted range where the appropriate edge of therange has been shifted to cover thenext data cell while stillcovering the current cell. |
Detailed documentation
getActiveRange()
Returns the selected range in the active sheet, ornull if there is no active range. Ifmultiple ranges are selected this method returns only the last selected range.
constselection=SpreadsheetApp.getActiveSpreadsheet().getSelection();constactiveRange=selection.getActiveRange();
Return
Range|null — The active range.
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
getActiveRangeList()
Returns the list of active ranges in the active sheet ornull if there are no activeranges.
If there is a single range selected, this behaves as aget call.
constsheet=SpreadsheetApp.getActiveSheet();// Returns the list of active ranges.constactiveRangeList=sheet.getActiveRangeList();
Return
Range — The list of active ranges.
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
getActiveSheet()
Returns the active sheet in the spreadsheet.
constselection=SpreadsheetApp.getActiveSpreadsheet().getSelection();constactiveSheet=selection.getActiveSheet();
Return
Sheet — The active sheet in the spreadsheet.
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
getCurrentCell()
Returns the current (highlighted) cell that is selected in one of the active ranges ornull if there is no current cell.
constselection=SpreadsheetApp.getActiveSpreadsheet().getSelection();// Returns the current highlighted cell in the one of the active ranges.constcurrentCell=selection.getCurrentCell();
Return
Range|null — The current cell.
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
getNextDataRange(direction)
Starting from thecurrent cell andactive rangeand moving in the given direction, returns an adjusted range where the appropriate edge of therange has been shifted to cover thenext data cell while stillcovering the current cell. If the active range is unbounded along thedimension of the direction, the original active range is returned. If there is no current cellor active range,null is returned. This is equivalent to selecting a range in theeditor and hittingCtrl+Shift+[arrow key].
// Assume the active spreadsheet is blank.constss=SpreadsheetApp.getActiveSpreadsheet();constsheet=ss.getSheets()[0];// Makes C3 the current cell and C3:E5 the active range.sheet.getRange('C3:E5').activate();// Logs 'C1:E3'console.log(SpreadsheetApp.getSelection().getNextDataRange(SpreadsheetApp.Direction.UP).getA1Notation(),);
Parameters
| Name | Type | Description |
|---|---|---|
direction | Direction | The direction in which to find the next data region edge cell. |
Return
Range|null — The adjusted range that includes the data cell, ornull if there is no selection.
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.