- Data Grid docs
- Columns and formatting
Columns
Resize, autosize, reorder, pin, hide and rename columns, and put bands over their headings, with the mouse, the keyboard or the view state.
People arrange columns the way they read them: wide enough for the text, the key fields first, the rest out of the way. The grid lets them do that with the mouse, with the keyboard through the Columns dialog, and lets your code do the same through the view state.
In the grid
- Resize: drag a heading's right edge. Widths run from 48 to 800 pixels.
- Autosize: double-click the edge, or choose Autosize column in the column menu, to fit the column to its text.
- Reorder: drag a heading to another place.
- Pin: Pin in the column menu keeps the column at the start while the others scroll sideways.
- Hide: Hide column in the column menu. At least one column stays visible.
- Rename: Rename column… in the column menu turns the heading into an input. Enter keeps the new caption, Escape cancels. The caption belongs to this view; the field keeps its name.
- Sparkline: Sparkline… in the column menu draws each cell as a small chart; see Sparklines and charts.
- Columns in the toolbar lists every column with its visibility, pin, order (Move up, Move down), width and number format. It is the way to do all of the above with a keyboard or on a phone. Its Row height sets the density.
From code
| Method | Does |
|---|---|
setColumn(field, patch) | Changes some settings of one column: hidden, pinned, width (48 to 800, null for automatic), format, total, rules, caption, sparkline. The scroll position stays. |
moveColumn(field, before?) | Moves a column before another one, or to the end |
autosizeColumn(field) | Fits a column to its heading and loaded values; resolves with the width |
setColumns(columns) | Replaces every column's settings and the order at once |
getColumn(field), getFields() | Read one column's settings, or the fields of the records |
scrollToColumn(field) | Scrolls a visible column into view |
In the state, columns lists the columns in display order (pinned ones show first), each { field, hidden, pinned, width, format, total, rules, caption, sparkline }. A resize or a move by the user fires stateChange with columns among the keys that changed.
JavaScript
import { mountTable } from '@8sheets/data-grid';
const grid = await mountTable(document.querySelector('#orders'), { title: 'Orders', data: orders });
await grid.setColumn('Order', { pinned: true, width: 90 });
await grid.setColumn('Notes', { hidden: true });
await grid.setColumn('Revenue', { width: 140, format: '#,##0.00 "EUR"' });
await grid.moveColumn('Revenue', 'Units'); // Revenue now comes before Units
await grid.autosizeColumn('Customer');
await grid.setColumn('Units', { caption: 'Qty' }); // the heading reads "Qty"; the field is still Units
// Remember widths and order as the user drags.
grid.on('stateChange', (e) => {
if (e.changed.includes('columns')) localStorage.setItem('order-columns', JSON.stringify(e.state.columns));
});React
import { useRef } from 'react';
import { DataGrid } from '@8sheets/data-grid-react';
export function Orders({ options }) {
const ref = useRef(null);
const toggleNotes = () => ref.current.setColumn('Notes', { hidden: !ref.current.getColumn('Notes')?.hidden });
return (
<>
<button onClick={toggleNotes}>Show or hide notes</button>
<button onClick={() => ref.current.autosizeColumn('Customer')}>Fit customer</button>
<div style={{ height: 480 }}><DataGrid ref={ref} options={options} /></div>
</>
);
}Vue
<script setup>
import { ref } from 'vue';
import { DataGrid } from '@8sheets/data-grid-vue';
defineProps({ options: Object });
const dataGrid = ref(null);
const toggleNotes = () => dataGrid.value.setColumn('Notes', { hidden: !dataGrid.value.getColumn('Notes')?.hidden });
</script>
<template>
<button @click="toggleNotes">Show or hide notes</button>
<button @click="dataGrid.autosizeColumn('Customer')">Fit customer</button>
<div style="height: 480px"><DataGrid ref="dataGrid" :options="options" /></div>
</template>Angular
import { Component, Input, ViewChild } from '@angular/core';
import { DataGridComponent, DataGridOptions } from '@8sheets/data-grid-angular';
@Component({
selector: 'app-orders',
imports: [DataGridComponent],
template: `
<button (click)="toggleNotes()">Show or hide notes</button>
<button (click)="grid.autosizeColumn('Customer')">Fit customer</button>
<eight-data-grid #grid [options]="options" style="height: 480px" />`,
})
export class Orders {
@Input() options: DataGridOptions = {};
@ViewChild('grid') grid!: DataGridComponent;
toggleNotes() {
this.grid.setColumn('Notes', { hidden: !this.grid.getColumn('Notes')?.hidden });
}
}A column's format is an Excel number format code; it overrides the field's own format in this view. Its caption overrides the field's caption in the same way: the headings and the exports use it.
Header bands
A band is a heading over several columns, such as "Person" over Name and Role, or "Volume, first half" over six month columns. Give the bands with the columnGroups option, or name one in each field's group:
const grid = await mountTable(el, {
data: prices,
columnGroups: [{ caption: 'Volume, first half', fields: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'] }],
});
// The same with fields: neighbouring columns of one band share it.
const fields = [
{ name: 'Name', type: 'string', group: 'Person' },
{ name: 'Role', type: 'string', group: 'Person' },
{ name: 'Office', type: 'string', group: 'Work' },
];
- A run of neighbouring columns of one band shares one cell over their headings. Moving a column away from its band splits the band into two cells with the same caption; columns outside any band have an empty cell above them.
- A band also splits where the pinned columns end, so each part stays over its own columns while the others scroll.
- A field listed in
columnGroupstakes that band; its owngroupcounts only whencolumnGroupsdoesn't name it. columnGroupsis live:setOptions({ columnGroups })changes the bands without a new mount. Fields'groupis reported bygetFields().- An export with
layout: truekeeps the bands as merged cells; see Export.
Open the live example for a band over month columns, or the tree example for bands from fields.
Wide tables
Only the columns near the viewport are drawn, so a table of hundreds of columns scrolls sideways as smoothly as a narrow one. A server source receives the column window as columnOffset and columnLimit and may return only those columns.
Limits
- Widths are in CSS pixels, from 48 to 800. A column without a width sizes to its content.
- Pinned columns always show first, whatever their place in
state.columns. - Header bands have one level: a band can't hold other bands. A band only sets the headings; it doesn't collapse, move or hide its columns together.