Active Grid

Pinning Utilities - Active Grid

Overview

The getPinningStyles utility calculates the necessary CSS styles for pinned columns. It handles positioning, offsets, and z-index to ensure pinned columns display correctly.

import { getPinningStyles } from '@workspace/active-grid';

const { style, isPinned, isLastLeftPinned, isFirstRightPinned } = 
  getPinningStyles(column);

getPinningStyles

Calculate pinning styles for a column.

Signature

function getPinningStyles<TData>(
  column: Column<TData>
): {
  style: React.CSSProperties;
  isPinned: boolean;
  isLastLeftPinned: boolean;
  isFirstRightPinned: boolean;
}

Return Value

{
  style: {
    position?: 'sticky';
    left?: number;
    right?: number;
    zIndex?: number;
  };
  isPinned: boolean;
  isLastLeftPinned: boolean;
  isFirstRightPinned: boolean;
}

Basic Usage

In Custom Header

import { Column } from '@tanstack/react-table';
import { getPinningStyles } from '@workspace/active-grid';

function CustomHeader<TData>({ column }: { column: Column<TData> }) {
  const { style, isPinned } = getPinningStyles(column);
  
  return (
    <div style={style} className={isPinned ? 'pinned-header' : ''}>
      {column.columnDef.header}
    </div>
  );
}

In Custom Cell

import { Cell } from '@tanstack/react-table';
import { getPinningStyles } from '@workspace/active-grid';

function CustomCell<TData>({ cell }: { cell: Cell<TData, unknown> }) {
  const { style, isPinned } = getPinningStyles(cell.column);
  
  return (
    <div style={style} className={isPinned ? 'pinned-cell' : ''}>
      {cell.getValue()}
    </div>
  );
}

Style Properties

position: 'sticky'

Applied when column is pinned:

const { style } = getPinningStyles(column);
// style.position = 'sticky'

left: number

Offset from left for left-pinned columns:

const { style } = getPinningStyles(column);
// For second left-pinned column:
// style.left = widthOfFirstColumn

right: number

Offset from right for right-pinned columns:

const { style } = getPinningStyles(column);
// For first right-pinned column:
// style.right = 0

zIndex: 1

Z-index for pinned columns:

const { style } = getPinningStyles(column);
// style.zIndex = 1

Boolean Flags

isPinned

Whether the column is pinned (left or right):

const { isPinned } = getPinningStyles(column);

if (isPinned) {
  // Column is pinned
}

isLastLeftPinned

Whether this is the last column pinned to the left:

const { isLastLeftPinned } = getPinningStyles(column);

if (isLastLeftPinned) {
  // Add border to separate from unpinned columns
}

isFirstRightPinned

Whether this is the first column pinned to the right:

const { isFirstRightPinned } = getPinningStyles(column);

if (isFirstRightPinned) {
  // Add border to separate from unpinned columns
}

Complete Example

Custom Header with Pinning

import { Column } from '@tanstack/react-table';
import { getPinningStyles } from '@workspace/active-grid';
import { cn } from '@/lib/utils';

type CustomHeaderProps<TData> = {
  column: Column<TData>;
  children: React.ReactNode;
};

function CustomHeader<TData>({ column, children }: CustomHeaderProps<TData>) {
  const {
    style,
    isPinned,
    isLastLeftPinned,
    isFirstRightPinned,
  } = getPinningStyles(column);
  
  return (
    <div
      style={style}
      className={cn(
        'grid-header-cell',
        isPinned && 'bg-background',
        isLastLeftPinned && 'border-r-2 border-primary',
        isFirstRightPinned && 'border-l-2 border-primary'
      )}
    >
      {children}
    </div>
  );
}

Custom Cell with Pinning

import { Cell } from '@tanstack/react-table';
import { getPinningStyles } from '@workspace/active-grid';

type CustomCellProps<TData, TValue> = {
  cell: Cell<TData, TValue>;
  children: React.ReactNode;
};

function CustomCell<TData, TValue>({
  cell,
  children,
}: CustomCellProps<TData, TValue>) {
  const {
    style,
    isPinned,
    isLastLeftPinned,
    isFirstRightPinned,
  } = getPinningStyles(cell.column);
  
  return (
    <div
      style={style}
      className={cn(
        'grid-cell',
        isPinned && [
          'bg-background',
          'shadow-sm',
        ],
        isLastLeftPinned && 'border-r',
        isFirstRightPinned && 'border-l'
      )}
    >
      {children}
    </div>
  );
}

Advanced Usage

With Conditional Styling

With Custom Z-Index

With Hover Effects

Styling Pinned Columns

Add Shadow to Last Left Pinned

Add Shadow to First Right Pinned

Custom Border Colors

Performance Considerations

The utility is lightweight and calculates styles on-demand:

TypeScript

Integration with ActiveGrid

The ActiveGrid uses getPinningStyles internally for all pinned columns. You typically only need this utility when creating custom header or cell components.

CSS Classes vs Inline Styles

The utility returns inline styles, but you can combine with CSS classes:

Debugging Pinning Issues

Check pinning styles in DevTools:

Best Practices

✅ DO

Calculate styles once per render
Combine with CSS classes
Use for custom components
Add borders to separate pinned columns
Test with different column widths

❌ DON'T

Don't calculate multiple times
Don't override position property
Don't skip z-index
Don't ignore border flags
Don't hardcode offsets

function CustomCell({ cell }) {
  const { style, isPinned } = getPinningStyles(cell.column);
  const [isHovered, setIsHovered] = useState(false);
  
  return (
    <div
      style={{
        ...style,
        backgroundColor: isPinned && isHovered ? '#f3f4f6' : undefined,
      }}
      onMouseEnter={() => setIsHovered(true)}
      onMouseLeave={() => setIsHovered(false)}
    >
      {cell.getValue()}
    </div>
  );
}

const { style, isLastLeftPinned, isFirstRightPinned } = getPinningStyles(column);

return (
  <div
    style={style}
    className={cn(
      isLastLeftPinned && 'border-r-2 border-blue-500',
      isFirstRightPinned && 'border-l-2 border-blue-500'
    )}
  >
    {children}
  </div>
);

// ✓ Good: Calculate once per render
const pinningStyles = getPinningStyles(column);

// ✗ Bad: Multiple calculations
const isPinned = getPinningStyles(column).isPinned;
const style = getPinningStyles(column).style;

import { Column } from '@tanstack/react-table';
import { getPinningStyles } from '@workspace/active-grid';

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

function MyComponent({ column }: { column: Column<User> }) {
  const {
    style,          // React.CSSProperties
    isPinned,       // boolean
    isLastLeftPinned,   // boolean
    isFirstRightPinned, // boolean
  } = getPinningStyles(column);
  
  return <div style={style}>{/* content */}</div>;
}

const { style, isPinned } = getPinningStyles(column);

return (
  <div
    style={style}
    className={cn(
      'grid-cell',
      isPinned && 'grid-cell--pinned'
    )}
  >
    {children}
  </div>
);

const pinningInfo = getPinningStyles(column);
console.log('Pinning info:', pinningInfo);
// {
//   style: { position: 'sticky', left: 150, zIndex: 1 },
//   isPinned: true,
//   isLastLeftPinned: false,
//   isFirstRightPinned: false
// }

Pinning Utilities