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.
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.
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.
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:
[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 cell | when |
|---|---|
data-pinned | start or end, where its column is pinned (a header cell: all of its columns) |
data-pinned-edge | it 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.
Column spanning
Let a cell or a header cell cover the columns after it, row by row, with the keys, the windows, pinned columns and ARIA following the span.
Column resizing
Columns a person resizes with a handle you render, dragged or moved with the arrows, within limits you set, the widths kept by the grid or by you.