Active Grid

Row Pinning - Active Grid

Overview

Row pinning allows users to pin important rows to the top or bottom of the grid, keeping them visible during scrolling.

<ActiveGrid
  enableRowPinning={true}
  maxPinnedRows={10}
  columns={columns}
  data={data}
  {...}
/>

Basic Usage

Enable row pinning:

<ActiveGrid
  enableRowPinning={true}
  columns={columns}
  data={data}
  {...}
/>

Configuration

enableRowPinning

Type: boolean
Default: false
Description: Enable row pinning functionality

<ActiveGrid
  enableRowPinning={true}
  {...}
/>

maxPinnedRows

Type: number
Default: 10
Description: Maximum number of pinned rows (top + bottom combined)

<ActiveGrid
  enableRowPinning={true}
  maxPinnedRows={5}
  {...}
/>

PinnedRowsBuffer

Interface for initial pinned rows:

interface PinnedRowsBuffer<TData> {
  top: TData[];
  bottom: TData[];
}

Initial Pinned Rows

const initialPinnedRows: PinnedRowsBuffer<User> = {
  top: [
    { id: '1', name: 'Admin User', role: 'admin' },
  ],
  bottom: [
    { id: '999', name: 'Total', role: 'summary' },
  ],
};

<ActiveGrid
  enableRowPinning={true}
  pinnedRows={initialPinnedRows}
  {...}
/>

Pinning via Row Menu

When row pinning is enabled, the row menu automatically shows:

Pin to Top
Pin to Bottom
Unpin

<ActiveGrid
  enableRowPinning={true}
  rowMenu={{
    features: {
      pin: true, // Show pin options (default: true)
    },
  }}
  {...}
/>

Programmatic Pinning

Pin Row to Top

function PinButton({ row }) {
  const handlePin = () => {
    row.pin('top');
  };
  
  return <Button onClick={handlePin}>Pin to Top</Button>;
}

Pin Row to Bottom

function PinButton({ row }) {
  const handlePin = () => {
    row.pin('bottom');
  };
  
  return <Button onClick={handlePin}>Pin to Bottom</Button>;
}

Unpin Row

function UnpinButton({ row }) {
  const handleUnpin = () => {
    row.pin(false);
  };
  
  return <Button onClick={handleUnpin}>Unpin</Button>;
}

Toggle Pin

function TogglePinButton({ row }) {
  const isPinned = row.getIsPinned();
  
  const handleToggle = () => {
    if (isPinned) {
      row.pin(false);
    } else {
      row.pin('top');
    }
  };
  
  return (
    <Button onClick={handleToggle}>
      {isPinned ? 'Unpin' : 'Pin'}
    </Button>
  );
}

Check Pin Status

// Check if row is pinned
const isPinned = row.getIsPinned(); // 'top' | 'bottom' | false

// Check if pinned to top
const isPinnedTop = row.getIsPinned() === 'top';

// Check if pinned to bottom
const isPinnedBottom = row.getIsPinned() === 'bottom';

Pin State Management

Controlled Pinning

Initial Pin State

Pin Indicators

Pinned rows automatically receive CSS classes:

Custom Styling

Pin Icons in Rows

Add visual indicators for pinned rows:

Pinning Summary Rows

Common use case: pin totals or summaries:

Pinning with Server Mode

Row pinning works with server mode, but pinned rows must be in the data:

Max Pinned Rows Enforcement

When maxPinnedRows is reached, pinning additional rows will:

Show a warning toast
Prevent pinning

Complete Example

Pinning Order

Rows are displayed in this order:

Pinned to top (in pin order)
Regular rows
Pinned to bottom (in pin order)

Persistence

Pinned row state can be persisted:

Best Practices

✅ DO

Use for important rows
Pin summary/total rows
Provide visual indicators
Set reasonable max limits
Allow unpinning easily
Save pin state

❌ DON'T

Don't pin too many rows
Don't hide unpin option
Don't skip visual feedback
Don't ignore max limits
Don't pin dynamically changing rows
Don't forget accessibility

Keyboard Shortcuts

Row pinning via row menu can be accessed with keyboard:

Shift + F10 - Open row menu
↑ ↓ - Navigate menu
Enter - Select option

Accessibility

Pinned rows include:

ARIA labels for pinned status
Visual indicators
Keyboard accessible pinning
Screen reader announcements

TypeScript

import { RowPinningState } from '@tanstack/react-table';

function UsersTable() {
  const [rowPinning, setRowPinning] = useState<RowPinningState>({
    top: [],
    bottom: [],
  });
  
  return (
    <ActiveGrid
      enableRowPinning={true}
      state={{ rowPinning }}
      onRowPinningChange={setRowPinning}
      {...}
    />
  );
}

<ActiveGrid
  enableRowPinning={true}
  settings={{
    rowClassRules: {
      'bg-blue-50 border-b-2 border-blue-500': (row) => 
        row.getIsPinned() === 'top',
      'bg-green-50 border-t-2 border-green-500': (row) => 
        row.getIsPinned() === 'bottom',
    },
  }}
  {...}
/>

{
  id: 'pin-indicator',
  header: '',
  size: 40,
  cell: ({ row }) => {
    const isPinned = row.getIsPinned();
    if (!isPinned) return null;
    
    return (
      <Pin 
        className={cn(
          "h-4 w-4",
          isPinned === 'top' && "text-blue-500",
          isPinned === 'bottom' && "text-green-500"
        )}
      />
    );
  },
}

const users = [
  { id: '1', name: 'John', revenue: 1000 },
  { id: '2', name: 'Jane', revenue: 2000 },
  { id: '3', name: 'Bob', revenue: 1500 },
];

const totalRow = {
  id: 'total',
  name: 'TOTAL',
  revenue: users.reduce((sum, u) => sum + u.revenue, 0),
};

<ActiveGrid
  enableRowPinning={true}
  data={users}
  pinnedRows={{
    top: [],
    bottom: [totalRow],
  }}
  settings={{
    rowClassRules: {
      'font-bold bg-muted': (row) => row.id === 'total',
    },
  }}
  {...}
/>

<ActiveGrid
  mode="server"
  fetchFn={async (params) => {
    const result = await api.getData(params);
    return {
      data: [
        ...result.pinnedTop,
        ...result.data,
        ...result.pinnedBottom,
      ],
      totalCount: result.total,
    };
  }}
  enableRowPinning={true}
  {...}
/>

import { useState } from 'react';
import { RowPinningState } from '@tanstack/react-table';
import { Pin, PinOff } from 'lucide-react';

type Order = {
  id: string;
  orderNumber: string;
  customer: string;
  amount: number;
  status: string;
};

function OrdersTable() {
  const [rowPinning, setRowPinning] = useState<RowPinningState>({
    top: [],
    bottom: [],
  });
  
  const columns: GridColumnDef<Order>[] = [
    {
      id: 'pin-status',
      header: '',
      size: 40,
      cell: ({ row }) => {
        const isPinned = row.getIsPinned();
        if (!isPinned) return null;
        
        return (
          <Pin 
            className={cn(
              "h-4 w-4",
              isPinned === 'top' && "text-blue-500",
              isPinned === 'bottom' && "text-green-500"
            )}
          />
        );
      },
    },
    {
      accessorKey: 'orderNumber',
      header: 'Order #',
    },
    {
      accessorKey: 'customer',
      header: 'Customer',
    },
    {
      accessorKey: 'amount',
      header: 'Amount',
      meta: {
        valueFormatter: (value) => `$${value.toFixed(2)}`,
      },
    },
    {
      accessorKey: 'status',
      header: 'Status',
    },
    {
      id: 'actions',
      header: 'Actions',
      cell: ({ row }) => {
        const isPinned = row.getIsPinned();
        
        return (
          <div className="flex gap-2">
            {!isPinned && (
              <>
                <Button
                  size="sm"
                  variant="ghost"
                  onClick={() => row.pin('top')}
                >
                  <Pin className="h-4 w-4 mr-1" />
                  Pin Top
                </Button>
                <Button
                  size="sm"
                  variant="ghost"
                  onClick={() => row.pin('bottom')}
                >
                  <Pin className="h-4 w-4 mr-1" />
                  Pin Bottom
                </Button>
              </>
            )}
            
            {isPinned && (
              <Button
                size="sm"
                variant="ghost"
                onClick={() => row.pin(false)}
              >
                <PinOff className="h-4 w-4 mr-1" />
                Unpin
              </Button>
            )}
          </div>
        );
      },
    },
  ];
  
  return (
    <ActiveGrid
      columns={columns}
      data={orders}
      enableRowPinning={true}
      maxPinnedRows={5}
      state={{ rowPinning }}
      onRowPinningChange={setRowPinning}
      rowMenu={{
        features: {
          pin: true,
        },
      }}
      settings={{
        rowClassRules: {
          'bg-blue-50 border-b-2 border-blue-500': (row) =>
            row.getIsPinned() === 'top',
          'bg-green-50 border-t-2 border-green-500': (row) =>
            row.getIsPinned() === 'bottom',
        },
      }}
    />
  );
}

import { RowPinningState } from '@tanstack/react-table';

type User = {
  id: string;
  name: string;
};

const [rowPinning, setRowPinning] = useState<RowPinningState>({
  top: [],
  bottom: [],
});

<ActiveGrid<User>
  enableRowPinning={true}
  state={{ rowPinning }}
  onRowPinningChange={setRowPinning}
  {...}
/>

Row Pinning