selection

Rows the user picks — to delete, to send, to compare. No feature is needed.

Type	{ readonly mode: 'none' | 'single' | 'multi'; readonly checkbox?: boolean; readonly click?: boolean; readonly keepOnFilter?: boolean; readonly canSelect?: (row: DataNode<T>, selection: SelectionState, context: unknown) => boolean | string }
Default	{ mode: 'none' }
Live update (update())	Yes
Angular	the [selection] input
<dz-grid>	the settings property: el.settings = { selection: … }
Declared in	packages/dom/src/settings.ts

What it does

• mode: 'none', 'single' (one row at a time) or 'multi'.
• checkbox: true: a column of boxes; in 'multi', a box in its header selects every row (on browser pages, the page shown).
• click: true: a click selects the row (Ctrl/Cmd+click adds or removes it, Shift+click a run in screen order). Without it a click only moves the focus, and rows are selected with Space or their box. With blocks of cells (range()), Shift+click belongs to the block: rows are then ticked by their box.
• keepOnFilter: true by default, a selected row stays selected while a filter or the search hides it; false clears the selection when they change. A sort or a page never does.
• canSelect(row, selection, context): your rule for a row joining the selection. true allows, false refuses, a text refuses and is said to the user. It is never asked to untick a row. It needs rules() from @dzgrid/dom/rules (texts -rules): without it, no row can be selected, and a missing-feature error says why.

Space toggles the focused row and Ctrl+A (Cmd+A) selects all. The selection holds row keys, not ids: the selectionChanged event gives it with its count, and idOfDataKey(key) gives an id back. After « select all » on a server’s pages it reads « every row the query matches, but these ».

Example

TypeScript

import { createGrid } from '@dzgrid/dom';
import { idOfDataKey } from '@dzgrid/core';
import { EN } from '@dzgrid/dom/locales/en';

type Seed = { id: string; plant: string; packets: number };

createGrid<Seed>(document.getElementById('seeds')!, {
  rows: [{ id: 's1', plant: 'Moon squash', packets: 12 }, { id: 's2', plant: 'Glass bean', packets: 0 }],
  columns: [{ id: 'plant', header: 'Plant' }, { id: 'packets', header: 'Packets', type: 'number' }],
  getRowId: (s) => s.id,
  messages: EN,
  selection: { mode: 'multi', checkbox: true, click: true },
  onEvent: (e) => {
    if (e.type === 'selectionChanged' && e.selection.mode === 'include') console.log([...e.selection.keys].map(idOfDataKey));
  },
});

Angular

import { Component } from '@angular/core';
import { DzGrid, type DzgColumnOrGroup } from '@dzgrid/angular';
import { EN } from '@dzgrid/dom/locales/en';

type Seed = { id: string; plant: string; packets: number };

@Component({
  selector: 'app-seeds',
  imports: [DzGrid],
  template: `<dz-grid [rows]="rows" [columns]="columns" [getRowId]="rowId" [messages]="messages"
    [selection]="{ mode: 'multi', checkbox: true, click: true }" (selectionChanged)="count = $event.count" />
    <p>{{ count ?? 'Some' }} selected</p>`,
})
export class Seeds {
  count: number | null = 0;
  readonly rows: Seed[] = [{ id: 's1', plant: 'Moon squash', packets: 12 }, { id: 's2', plant: 'Glass bean', packets: 0 }];
  readonly columns: DzgColumnOrGroup<Seed>[] = [{ id: 'plant', header: 'Plant' }, { id: 'packets', header: 'Packets', type: 'number' }];
  readonly rowId = (s: Seed) => s.id;
  readonly messages = EN;
}

Web Component

import '@dzgrid/element/define';
import type { DzGridElement } from '@dzgrid/element';
import { EN } from '@dzgrid/dom/locales/en';

type Seed = { id: string; plant: string; packets: number };

const grid = document.querySelector<DzGridElement<Seed>>('dz-grid')!;
grid.columns = [{ id: 'plant', header: 'Plant' }, { id: 'packets', header: 'Packets', type: 'number' }];
grid.getRowId = (s) => s.id;
grid.messages = EN;
grid.settings = { selection: { mode: 'multi', checkbox: true, click: true } };
grid.rows = [{ id: 's1', plant: 'Moon squash', packets: 12 }, { id: 's2', plant: 'Glass bean', packets: 0 }];

Live demo

Click a row, Ctrl/Cmd+click another, Shift+click a third; the header's box selects all.

See also

• context — what canSelect is also given.
• Selection and ranges.