# Multi-Range Selection
URL: https://pro.rv-grid.com/guides/data-manage/multi-range-selection/
Source: src/content/docs/guides/data-manage/multi-range-selection.mdx
Description: Select, clear, and copy multiple disjoint RevoGrid ranges.
`MultiRangeSelectionPlugin` adds spreadsheet-style disjoint range selection while
leaving the native RevoGrid active range in charge of focus, Shift extension, and
editing.

Use it when users need to compare, clear, or copy multiple non-contiguous regions from the
same grid.

  Select a range, Ctrl/Cmd+click another cell, Shift+click to extend the new
  range, then copy. Plain-text clipboard output includes selected cells only, so
  paste does not clear gap cells between disjoint ranges.

## Usage

```ts
import { MultiRangeSelectionPlugin } from '@revolist/revogrid-pro';

const grid = document.createElement('revo-grid');
grid.range = true;
grid.plugins = [MultiRangeSelectionPlugin];
```

Cross-viewport autofill is enabled by default when this plugin is installed.
Users can drag the autofill handle between pinned and main row or column
viewports, and the committed result is stored as multiple selected ranges.
Disable only that drag integration with:

```ts
grid.multiRangeSelection = { crossViewportAutofill: false };
```

## User Behavior

1. Select a cell or range normally.
2. Ctrl/Cmd+click another cell to keep the previous range and start a new active range.
3. Shift+click or Shift+Arrow extends only the active range.
4. Tab and Enter move the focused cell inside the active range.
5. Delete and Backspace clear inactive ranges plus the active range.
6. Copy includes inactive ranges plus the active range.
7. Dragging the autofill handle across pinned/main viewport boundaries fills the visible target segments.
8. Plain click clears inactive ranges and starts a normal selection.

## Clipboard Shape

Multi-range copy preserves relative shape for nearby ranges in `text/plain`.
For example, diagonal selected cells are copied with blank cells between them so
external spreadsheets can keep the diagonal layout instead of stacking values
one after another. RevoGrid also writes a custom multi-range clipboard payload;
when the payload is pasted back into RevoGrid, only the selected cells are
edited, so the blank gaps do not clear existing destination values. Very large
sparse selections fall back to selected rectangular blocks to avoid huge
clipboard payloads. Rich `text/html` output mirrors the selected clipboard
shape.

Pinned and regular viewport coordinates are normalized into whole-grid visual
order before copy, so a pinned-left cell followed by the first regular cell is
copied as adjacent clipboard columns.

If only one range is selected, RevoGrid keeps its default copy behavior.

## Programmatic API

Call the public methods on the plugin instance:

```ts
const plugin = (await grid.getPlugins())
  .find(plugin => plugin instanceof MultiRangeSelectionPlugin);

plugin?.setSelectedRanges([
  { rowType: 'rgRow', colType: 'rgCol', range: { x: 0, y: 0, x1: 1, y1: 1 } },
  { rowType: 'rgRow', colType: 'rgCol', range: { x: 3, y: 0, x1: 3, y1: 1 } },
]);

const ranges = plugin?.getSelectedRanges();
plugin?.clearSelectedRanges();
```

The grid also dispatches `multirangeselectionchange` whenever the selected ranges
change.

## Rendering

Inactive cells receive:

- attribute: `multi-range-selection`
- class: `multi-range-selection-cell`
- edge classes for the range perimeter

The active range remains the native RevoGrid selection overlay.
