- Data Grid docs
- Rows and records
Pinned rows, moving and numbers
Keep records above or below the scrolling ones, move records by dragging their grip or with the keyboard, drag records from one grid to another, and number the rows.
Some records should stay in sight: the account being compared with the others, a benchmark, a running total from your server. Pinned rows keep them above or below the records that scroll, whatever the search, filters and sort. When the order is the user's to choose, as in a priority list or a playlist, rows can be moved by dragging, and records can be dragged from one grid into another. Row numbers show each record's place in the result.
Open the live example: pin a row, drag rows by their grip
In the grid
- Pin: Pin row to top or Pin row to bottom in a cell's context menu keeps the record there; Unpin row lets it go. Pinned records stay put while the others scroll, and the search, filters and sort don't move or hide them.
- Move: with
rowDrag: true, each row has a grip at its start. Drag it to move the record; when the record is among the selected ones, every selected record moves together. The context menu's Move up and Move down, and Alt+Up and Alt+Down on a focused record, move it one place. - Drag to another grid: drop rows on a grid mounted with
rowDrop: trueto hand the records to it. - Row numbers: with
rowNumbers: true, each row shows the record's number among the matching records, in their current order.
Moving needs the records in their own order: with a sort, groups or a tree, the grid says "Clear the sort and the groups to move records." Pinned records don't move; unpin them first.
From code
| Option, state or method | Does |
|---|---|
pinnedRows: { top, bottom } | In the state: the IDs of the records kept above and below the scrolling ones |
pinRows(ids, where?) | Pins records to 'top' (the default) or 'bottom' |
unpinRows(ids?) | Unpins some records, or every pinned record |
getPinnedRows() | { top, bottom }, the pinned IDs |
rowDrag: true | Shows a grip in each row for moving records |
moveRecords(ids, before?) | Moves records before another record, or to the end with null; resolves false when a rowMove handler cancelled |
rowDrop: true | Takes records dragged from another grid |
rowNumbers: true | Shows each record's number among the matching records |
The options are live, so setOptions({ rowDrag: true }) turns moving on without a new mount.
| Event | Payload | Cancellable | When |
|---|---|---|---|
rowMove | { ids, before, source } | yes: nothing moves | Records are about to move, by a drag, the menu, the keyboard or moveRecords() |
rowDrop | { records, source } | yes: an editable grid adds nothing | Records from another grid were dropped on this one |
After a local move, the change event reports { action: 'move', ids, before }, and the new order is the grid's own from then on. rowDrop gives records with every field ({ id, values, raw }) and source, the grid they came from. An editable grid on local records then adds them, with the fields the two grids share, as one undo step that goes through beforeAdd and the field rules; a read-only grid or a server source leaves them to your handler. The source grid keeps its records: to move rather than copy them, remove them there in the handler.
JavaScript
import { mountTable } from '@8sheets/data-grid';
const backlog = await mountTable(document.querySelector('#backlog'), {
title: 'Backlog',
data: tasks,
rowDrag: true,
rowNumbers: true,
rowSelection: 'multiple',
// Keep the new order on your server.
onRowMove: (e) => {
fetch('/api/tasks/order', { method: 'POST', body: JSON.stringify({ ids: e.ids, before: e.before }) });
},
});
const sprint = await mountTable(document.querySelector('#sprint'), {
title: 'This sprint',
fields: taskFields, // the fields the dropped records bring along
data: [],
editable: true,
rowDrop: true,
onRowDrop: (e) => {
if (e.records.length > 10) e.preventDefault(); // too many at once: add none
},
});
await backlog.pinRows([17]); // the blocker stays on top
await backlog.moveRecords([42], 7); // task 42 now comes before task 7React
import { useMemo, useRef } from 'react';
import { DataGrid } from '@8sheets/data-grid-react';
export function Backlog({ tasks }) {
const ref = useRef(null);
const options = useMemo(() => ({ title: 'Backlog', data: tasks, rowDrag: true, rowNumbers: true }), [tasks]);
const pinFocused = () => {
const cell = ref.current.getFocusedCell();
if (cell) ref.current.pinRows([cell.id], 'top');
};
return (
<>
<button onClick={pinFocused}>Pin to top</button>
<button onClick={() => ref.current.unpinRows()}>Unpin all</button>
<div style={{ height: 480 }}>
<DataGrid ref={ref} options={options} onRowMove={(e) => saveOrder(e.ids, e.before)} />
</div>
</>
);
}Vue
<script setup>
import { computed, ref } from 'vue';
import { DataGrid } from '@8sheets/data-grid-vue';
const props = defineProps({ tasks: Array });
const options = computed(() => ({ title: 'Backlog', data: props.tasks, rowDrag: true, rowNumbers: true }));
const dataGrid = ref(null);
function pinFocused() {
const cell = dataGrid.value.getFocusedCell();
if (cell) dataGrid.value.pinRows([cell.id], 'top');
}
</script>
<template>
<button @click="pinFocused">Pin to top</button>
<button @click="dataGrid.unpinRows()">Unpin all</button>
<div style="height: 480px">
<DataGrid ref="dataGrid" :options="options" @row-move="(e) => saveOrder(e.ids, e.before)" />
</div>
</template>Angular
import { Component, Input, ViewChild } from '@angular/core';
import { DataGridComponent, DataGridOptions } from '@8sheets/data-grid-angular';
@Component({
selector: 'app-backlog',
imports: [DataGridComponent],
template: `
<button (click)="pinFocused()">Pin to top</button>
<button (click)="grid.unpinRows()">Unpin all</button>
<eight-data-grid #grid [options]="options" (rowMove)="moved($event)" style="height: 480px" />`,
})
export class Backlog {
@ViewChild('grid') grid!: DataGridComponent;
options: DataGridOptions = {};
@Input() set tasks(data: Record<string, unknown>[]) {
this.options = { title: 'Backlog', data, rowDrag: true, rowNumbers: true };
}
pinFocused() {
const cell = this.grid.getFocusedCell();
if (cell) this.grid.pinRows([cell.id], 'top');
}
moved(e: { ids: (string | number)[]; before: string | number | null }) {
saveOrder(e.ids, e.before);
}
}With a server source
- Pinned rows: a source opts in with
pinnedRows: true(remoteTableSource({ pinnedRows: true })). The grid then sendspinnedRowsin the view state, and each page answers withpinned: { top, bottom }, the pinned records as rows of the page's columns. Without the flag, the grid doesn't offer pinning, andpinRowsrejects with "This source cannot pin rows."tableQueryServicein the source download answerspinned. - Moving: the server keeps the order, so the grid only fires
rowMove. Move the records on your server in the handler, then callrefresh(). - Row numbers: a record row may carry its
number, its place among the matching records.
const grid = await mountTable(el, {
fields,
dataSource: remoteTableSource({ queryUrl: '/api/tasks/query', pinnedRows: true }),
rowDrag: true,
onRowMove: async (e) => {
await fetch('/api/tasks/move', { method: 'POST', body: JSON.stringify({ ids: e.ids, before: e.before }) });
await grid.refresh();
},
});
Limits
- Moving works only while the records are in their own order: no sort, groups or tree.
- A local move changes the order in the grid, not your data: save it from
rowMoveorchangeif it should last. - Dragging between grids works between grids on the same page.
- A pinned record shows even when it doesn't match the search or filters, and it keeps its place whatever the sort.