1. Data Grid docs
  2. 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.

Open the columns example

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

MethodDoes
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 columnGroups takes that band; its own group counts only when columnGroups doesn't name it.
  • columnGroups is live: setOptions({ columnGroups }) changes the bands without a new mount. Fields' group is reported by getFields().
  • An export with layout: true keeps 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.