Pinned Columns Plugin

The Pinned Columns plugin freezes columns to the left or right edge of the grid—essential for keeping key identifiers or action buttons visible while scrolling through wide datasets. Just set pinned: 'left' or pinned: 'right' on your column definitions and the plugin handles the rest.

Installation

import '@toolbox-web/grid/features/pinned-columns';

Basic Usage

Pin important columns like ID on the left and action buttons on the right. The pinned columns stay fixed while the middle content scrolls horizontally.

Vanilla JS

import { queryGrid } from '@toolbox-web/grid';

const grid = queryGrid('tbw-grid');
grid.gridConfig = {
  columns: [
    { field: 'id', header: 'ID', pinned: 'left', width: 80 },
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email' },
    { field: 'department', header: 'Department' },
    { field: 'salary', header: 'Salary', type: 'currency' },
    { field: 'actions', header: 'Actions', pinned: 'right', width: 120 },
  ],
  features: { pinnedColumns: true },
};

React

import '@toolbox-web/grid-react/features/pinned-columns';
import { DataGrid } from '@toolbox-web/grid-react';

function EmployeeGrid({ employees }) {
  return (
    <DataGrid
      rows={employees}
      columns={[
        { field: 'id', header: 'ID', pinned: 'left', width: 80 },
        { field: 'name', header: 'Name' },
        { field: 'email', header: 'Email' },
        { field: 'department', header: 'Department' },
        { field: 'salary', header: 'Salary', type: 'currency' },
        { field: 'actions', header: 'Actions', pinned: 'right', width: 120 },
      ]}
      pinnedColumns
    />
  );
}

Vue

<script setup>
import '@toolbox-web/grid-vue/features/pinned-columns';
import { TbwGrid } from '@toolbox-web/grid-vue';

const employees = [
  { id: 1, name: 'Alice', email: 'alice@example.com', department: 'Engineering', salary: 95000 },
  { id: 2, name: 'Bob', email: 'bob@example.com', department: 'Marketing', salary: 75000 },
];

const columns = [
  { field: 'id', header: 'ID', pinned: 'left', width: 80 },
  { field: 'name', header: 'Name' },
  { field: 'email', header: 'Email' },
  { field: 'department', header: 'Department' },
  { field: 'salary', header: 'Salary', type: 'currency' },
  { field: 'actions', header: 'Actions', pinned: 'right', width: 120 },
];
</script>

<template>
  <TbwGrid :rows="employees" :columns="columns" pinned-columns />
</template>

Angular

// Feature import - enables the [pinnedColumns] input
import '@toolbox-web/grid-angular/features/pinned-columns';

import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { ColumnConfig } from '@toolbox-web/grid';

@Component({
  selector: 'app-employee-grid',
  imports: [Grid],
  template: `
    <tbw-grid
      [rows]="rows"
      [columns]="columns"
      [pinnedColumns]="true"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class EmployeeGridComponent {
  rows = [];

  columns: ColumnConfig[] = [
    { field: 'id', header: 'ID', pinned: 'left', width: 80 },
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email' },
    { field: 'department', header: 'Department' },
    { field: 'salary', header: 'Salary', type: 'currency' },
    { field: 'actions', header: 'Actions', pinned: 'right', width: 120 },
  ];
}

Demo

PIN COLUMNS

ID

noneleftright

Name

noneleftright

Email

noneleftright

Department

noneleftright

Phone

noneleftright

Address

noneleftright

City

noneleftright

Country

noneleftright

Actions

noneleftright

Show source

Use the controls below to change which columns are pinned to the left, right, or not pinned. Pinned columns are automatically reordered to the grid edges—left-pinned columns move to the start, right-pinned columns move to the end. Unpinning restores the column to its original position.

Configuration Options

The plugin has no configuration options. It is activated when columns have pinned: 'left' or pinned: 'right' set.

Programmatic API

See PinnedColumnsPlugin for the full list of methods.

const plugin = grid.getPluginByName('pinnedColumns');

// Get currently pinned columns
const leftPinned = plugin.getLeftPinnedColumns();
const rightPinned = plugin.getRightPinnedColumns();

// Clear all sticky positions
plugin.clearStickyPositions();

// Recalculate offsets (e.g., after column resize)
plugin.refreshStickyOffsets();

Note

To pin or unpin columns at runtime, update the column’s pinned property in your gridConfig.columns and re-assign the config. The plugin reads pinned from column definitions during each render cycle.

RTL Support

For direction-independent pinning, use logical values 'start' and 'end' instead of 'left'/'right':

{ field: 'id', pinned: 'start' }  // Left in LTR, Right in RTL
{ field: 'actions', pinned: 'end' } // Right in LTR, Left in RTL

Column Reordering Behaviour

When a column is pinned (either via config or the context menu), the plugin automatically reorders it to the appropriate edge of the grid:

• pinned: 'left' → moved to the leftmost position (after other left-pinned columns)
• pinned: 'right' → moved to the rightmost position (before other right-pinned columns)

When a column is unpinned via the context menu, it is restored to its original position in the column order.

This ensures pinned columns are always visible at the grid edges without requiring the user to scroll.

Known Limitations

• Incompatible with Column Groups: Pinned columns cannot be used together with the Column Groups plugin. Pinning reorders columns to the grid edges, but moving a column out of its column group is not supported. When both plugins are loaded, a development-mode warning is shown and the pin/unpin context menu items are hidden.

• Header-only sticky in virtualized grids: Due to the row virtualization architecture (will-change: transform on the rows container), position: sticky only works on header cells. Data row cells receive the sticky CSS classes but the browser cannot honour them because the transformed ancestor creates a new containing block.

See Also

• Pinned Rows — Pin rows to top/bottom
• Column Reorder — Drag-to-reorder columns
• Column Groups — Group column headers