Selection

Access the current active selection in the active sheet. A selection is the set of cells the user
has highlighted in the sheet, which can be non-adjacent ranges. One cell in the selection is the
*current cell*, where the user's current focus is. The current cell is highlighted with a
darker border in the Google Sheets UI.

```javascript
const activeSheet = SpreadsheetApp.getActiveSheet();
const rangeList = activeSheet.getRangeList(['A1:B4', 'D1:E4']);
rangeList.activate();

const selection = activeSheet.getSelection();
// Current Cell: D1
console.log(`Current Cell: ${selection.getCurrentCell().getA1Notation()}`);
// Active Range: D1:E4
console.log(`Active Range: ${selection.getActiveRange().getA1Notation()}`);
// Active Ranges: A1:B4, D1:E4
const ranges = selection.getActiveRangeList().getRanges();
for (let i = 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 |
|---|---|---|
| `https://developers.google.com/apps-script/reference/spreadsheet/selection#getActiveRange()` | `https://developers.google.com/apps-script/reference/spreadsheet/range|null` | Returns the selected range in the active sheet, or `null` if there is no active range. |
| `https://developers.google.com/apps-script/reference/spreadsheet/selection#getActiveRangeList()` | `https://developers.google.com/apps-script/reference/spreadsheet/range-list|null` | Returns the list of active ranges in the active sheet or `null` if there are no active ranges. |
| `https://developers.google.com/apps-script/reference/spreadsheet/selection#getActiveSheet()` | `https://developers.google.com/apps-script/reference/spreadsheet/sheet` | Returns the active sheet in the spreadsheet. |
| `https://developers.google.com/apps-script/reference/spreadsheet/selection#getCurrentCell()` | `https://developers.google.com/apps-script/reference/spreadsheet/range|null` | Returns the current (highlighted) cell that is selected in one of the active ranges or `null` if there is no current cell. |
| `https://developers.google.com/apps-script/reference/spreadsheet/selection#getNextDataRange(Direction)` | `https://developers.google.com/apps-script/reference/spreadsheet/range|null` | Starting from the `https://developers.google.com/apps-script/reference/spreadsheet/selection#getCurrentCell()` and `https://developers.google.com/apps-script/reference/spreadsheet/selection#getActiveRange()` and moving in the given direction, returns an adjusted range where the appropriate edge of the range has been shifted to cover the `https://developers.google.com/apps-script/reference/spreadsheet/range#getNextDataCell(Direction)` while still covering the current cell. |

## Detailed documentation

### `getActiveRange()`

Returns the selected range in the active sheet, or `null` if there is no active range. If
multiple ranges are selected this method returns only the last selected range.

```javascript
const selection = SpreadsheetApp.getActiveSpreadsheet().getSelection();
const activeRange = selection.getActiveRange();
```

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/range|null` --- The active range.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/spreadsheets.currentonly`
- `https://www.googleapis.com/auth/spreadsheets`

*** ** * ** ***

### `getActiveRangeList()`

Returns the list of active ranges in the active sheet or `null` if there are no active
ranges.

If there is a single range selected, this behaves as a `https://developers.google.com/apps-script/reference/spreadsheet/selection#getActiveRange()` call.

```javascript
const sheet = SpreadsheetApp.getActiveSheet();
// Returns the list of active ranges.
const activeRangeList = sheet.getActiveRangeList();
```

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/range-list|null` --- The list of active ranges.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/spreadsheets.currentonly`
- `https://www.googleapis.com/auth/spreadsheets`

*** ** * ** ***

### `getActiveSheet()`

Returns the active sheet in the spreadsheet.

```javascript
const selection = SpreadsheetApp.getActiveSpreadsheet().getSelection();
const activeSheet = selection.getActiveSheet();
```

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/sheet` --- The active sheet in the spreadsheet.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/spreadsheets.currentonly`
- `https://www.googleapis.com/auth/spreadsheets`

*** ** * ** ***

### `getCurrentCell()`

Returns the current (highlighted) cell that is selected in one of the active ranges or `null` if there is no current cell.

```javascript
const selection = SpreadsheetApp.getActiveSpreadsheet().getSelection();
// Returns the current highlighted cell in the one of the active ranges.
const currentCell = selection.getCurrentCell();
```

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/range|null` --- The current cell.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/spreadsheets.currentonly`
- `https://www.googleapis.com/auth/spreadsheets`

*** ** * ** ***

### `getNextDataRange(direction)`

Starting from the `https://developers.google.com/apps-script/reference/spreadsheet/selection#getCurrentCell()` and `https://developers.google.com/apps-script/reference/spreadsheet/selection#getActiveRange()`
and moving in the given direction, returns an adjusted range where the appropriate edge of the
range has been shifted to cover the `https://developers.google.com/apps-script/reference/spreadsheet/range#getNextDataCell(Direction)` while still
covering the current cell. If the active range is unbounded along the `https://developers.google.com/apps-script/reference/spreadsheet/dimension` of the direction, the original active range is returned. If there is no current cell
or active range, `null` is returned. This is equivalent to selecting a range in the
editor and hitting `Ctrl+Shift+[arrow key]`.

```javascript
// Assume the active spreadsheet is blank.
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = 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` | `https://developers.google.com/apps-script/reference/spreadsheet/direction` | The direction in which to find the next data region edge cell. |

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/range|null` --- The adjusted range that includes the data cell, or `null` if there is no
selection.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/spreadsheets.currentonly`
- `https://www.googleapis.com/auth/spreadsheets`