Documentation
Concepts

Pinned columns

Keep the leading and trailing columns in view while the others scroll sideways, under virtualization and scroll scaling, as divs or as a table.

A pinned column stays at the start or at the end of the view while the other columns scroll sideways: a row number, a name, the columns that say which row you are reading at the start; a total, a status or the row's actions at the end. Its cells stay in their rows, in the same markup, as divs or as a real table.

Pinned columns
Gallery

Install pinning

Pinning is a feature: columnPinning() from the /column-pinning entry. It has no props: installed, the columns' pinned keeps them in view. Without it, pinned is ignored: every column scrolls, no cell is sticky or carries data-pinned, and get("pinned-column-keys") does not compile. The parts a pinned declares stay the core's column model either way: the same validation, spans that never cross a part, and moves within a part, so a list of columns means the same with and without pinning. The layers the grid writes (the sticky insets, the windows between the strips) are the core's too, and lay nothing out without pinned columns in effect.

people.tsx
import { columnPinning } from "@fragiola/data-grid-react/column-pinning";
import { navigation } from "@fragiola/data-grid-react/navigation";

const features = [navigation(), columnPinning()];

Pinning a column

Give the leading columns pinned: "start" and the trailing ones pinned: "end". The columns pinned at the start come first, the ones pinned at the end last, and a group's columns are all in one part: a group whose columns are pinned is pinned with them.

columns.tsx
const columns: ColumnOrGroup<Person>[] = [
    {
        key: "person",
        name: "Person",
        children: [
            { key: "name", name: "Name", width: 180, pinned: "start" },
            { key: "team", name: "Team", width: 120, pinned: "start" },
        ],
    },
    // … the columns that scroll
    {
        key: "summary",
        name: "Summary",
        children: [
            { key: "average", name: "Average", width: 96, pinned: "end" },
            { key: "best", name: "Best", width: 96, pinned: "end" },
        ],
    },
];

A column pinned at the start after one that is not, a column after one pinned at the end, or a group mixing parts, is refused like any invalid column (columns.set fails, and a grid never starts with them).

What stays in view

Pinned columns are always rendered, wherever the view is: the ones pinned at the start first in each row, the ones pinned at the end last. The column window (onColumnWindowChange, useColumnWindow) describes the columns that scroll: the view between the two pinned parts. Bringing a cell into view (the keyboard, scroll-to-cell) leaves it between them, never under them, and a pinned cell is always in view: it never scrolls sideways. The columns pinned at the end sit at the view's end, or, in a grid narrower than its view, right after the other columns.

When the pinned columns of both parts are as wide as the view or wider (a narrow screen), they would hide every other column: they scroll with the rest until the view is wider again. get("pinned-column-keys") reads the columns pinned as declared, { start, end }, their keys.

A column moves only within its part (reordering), and a column pinned at the end flexes and fits like any other; it resizes from its start edge, its boundary with the columns that scroll (state.edge is "start"). In a right-to-left grid the start is the right edge: the columns pinned at the start sit there, the ones pinned at the end on the left.

Stacking is yours

The grid keeps pinned cells in place; what is painted on top of the cells that scroll is yours (the header's and the summary rows' place above the body is the grid's). Make pinned cells opaque and above the cells that scroll under them:

grid.css
[data-grid-part="cell"][data-pinned],
[data-grid-part="header-cell"][data-pinned] {
    background: var(--surface);
    z-index: 1;
}

/* a pinned part's edge: a line or a shadow where the others pass under it */
[data-pinned="start"][data-pinned-edge] {
    box-shadow: 6px 0 8px -6px rgb(0 0 0 / 0.3);
}
[data-pinned="end"][data-pinned-edge] {
    box-shadow: -6px 0 8px -6px rgb(0 0 0 / 0.3);
}

A row's box holds the pinned cells: it starts both parts' width and the rendered columns' width before its layer, and with columns pinned at the end it reaches past the last rendered column by their width and the rendered columns' width again, so sticky holds them at the view's end through a scroll not rendered yet (with every column pinned, it holds them all where they are). A row's background and its hover cover them. A row stripe that is translucent needs painting on the pinned cell too, over its opaque background (the example does it from the cell's state).

Pinned cells are position: sticky, and sticky holds to the nearest element that scrolls. Never give a row, a header row, Body or Header an overflow other than visible or clip: overflow: hidden or auto makes that element the one they hold to, and they scroll away with the rest. Use overflow: clip to cut a row's content. A cell's own overflow is free.

With pinned columns, a row (and a header row) is a flex container its pinned cells sit in: render them as the row's own children (no wrapper between Row and its cells), and give the row no padding, flex-direction or flex-wrap of yours, or the pinned cells leave the line the cells that scroll are on.

What it shows

on a cell or header cellwhen
data-pinnedstart or end, where its column is pinned (a header cell: all of its columns)
data-pinned-edgeit is its part's edge: it ends at the last column pinned at the start, or starts at the first pinned at the end

useCell and useHeaderCell report the same as pinned (either part), pinnedSide ("start" or "end") and pinnedEdge. ARIA does not change: the DOM order is the columns' order, and aria-colindex is the column's.

How it works

A pinned cell is position: sticky in its row's flow, the ones pinned at the end after the ones pinned at the start, and the row is a flex container: the browser keeps the cell in place as it scrolls, on every frame it paints, a fling and the scrollbar's thumb included. The grid writes the cell's left inset (right right to left), the offset that cancels its layer's, and for a column pinned at the end the way to the view's end: unscaled it changes only when a new column window renders or the view's width changes, never while you scroll, and under scroll scaling it is written with the grid's own moves, in the same frame. A transform or an inset (top, left, right, bottom, inset) you give a pinned cell is dropped, since sticky would obey it. A grid without pinned columns renders as before: no flex rows, no sticky cells.