1. Data Grid docs
  2. 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: true to 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 methodDoes
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: trueShows 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: trueTakes records dragged from another grid
rowNumbers: trueShows each record's number among the matching records

The options are live, so setOptions({ rowDrag: true }) turns moving on without a new mount.

EventPayloadCancellableWhen
rowMove{ ids, before, source }yes: nothing movesRecords are about to move, by a drag, the menu, the keyboard or moveRecords()
rowDrop{ records, source }yes: an editable grid adds nothingRecords 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 7

React

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 sends pinnedRows in the view state, and each page answers with pinned: { top, bottom }, the pinned records as rows of the page's columns. Without the flag, the grid doesn't offer pinning, and pinRows rejects with "This source cannot pin rows." tableQueryService in the source download answers pinned.
  • Moving: the server keeps the order, so the grid only fires rowMove. Move the records on your server in the handler, then call refresh().
  • 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 rowMove or change if 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.