# Row pinning (top / bottom) Pin specific rows to the **top** or **bottom** of the grid so they stay visible while the rest of the data scrolls. Typical use cases: - A **totals** or **aggregate** row anchored at the top of a long ledger. - An **industry benchmark** or **target** row for at-a-glance comparison. - A **page totals** row at the bottom that recomputes as filters narrow the visible set. - A **headline metric** (e.g. "Closing balance") that should never scroll out of view. > Live demo: Pinned rows (engine prop) - https://svgrid.com/demos/108-pinned-rows-engine/ ## Props `` accepts two props: The examples on this page run against these rows: ```svelte ``` ```ts pinnedTopRows?: ReadonlyArray pinnedBottomRows?: ReadonlyArray ``` Each is an array of your own row objects (same `TData` type as `data`). The grid renders them inside the same table as the regular rows, with `position: sticky` so they track the scroll. They share the column schema (widths, pinning, `format`, `cellClass`) - you do not redefine columns. ## Quick start ```ts ``` The totals row sticks under the header and stays in view while the user scrolls. ## Filter-aware "page totals" at the bottom The grid exposes `api.getDisplayedRows()` - the post-filter / post-sort / post-pagination row set. Combine it with `pinnedBottomRows` for a "page total" that updates as filters narrow the data. ```ts (api = next)} /> ``` ## Multiple pinned rows Pass more than one row in either array; the grid stacks them. The first row sticks closest to the header (top) or to the bottom edge (bottom). ```svelte ``` The built-in CSS supports stacking up to 4 rows per side. For larger stacks, override the CSS variables yourself: ```css .sv-grid-pinned-row-top[data-pinned-index="4"] td { top: calc(var(--sg-thead-h, 36px) + var(--sg-pinned-row-h, 32px) * 4); } ``` ## How pinned rows behave | Behavior | Regular rows | Pinned rows | | --- | --- | --- | | Inline editing | Yes (when `enableInlineEditing`) | No | | Selection checkbox | Yes (when enabled) | No (cell rendered empty) | | Cell selection rectangle | Yes | No (cells skipped) | | Sorting | Yes | No (pinned rows are in a separate ``) | | Filtering | Yes | No (pinned rows are not filtered) | | Fill handle | Yes | No | | `cellClass` | Yes | Yes (a function gets `row: null` and the pinned value) | | `format`, `formatter` | Yes | Yes | | `align` | Yes | Yes | | Column pinning (left/right) | Yes | Yes | Pinned rows are **read-only by design** - they represent aggregates or annotations, not transactional data. For an editable band at the top, freeze the grid's own rows instead: see below. ## Frozen rows (`frozenRows`) `frozenRows={N}` keeps the first N rows under the header while the body scrolls, Excel's Freeze Panes for the row half (`columnPinning` is the column half). Unlike pinned rows they are the grid's own rows: numbered 1..N, editable, selectable, sortable with the rest, dragged taller with `rowResize`. Under `virtualization` they are always rendered and the window skips them. ```svelte ``` `api.setOption('frozenRows', n)` changes it at runtime and `undefined` clears it; the spreadsheet shell's Freeze and Unfreeze buttons do exactly that, at the active cell, and keep the setting per sheet. ## Styling Pinned rows expose two CSS variables on the grid shell that you can override: ```css .sv-grid-shell { --sg-pinned-bg: color-mix(in oklab, #6366f1 4%, #ffffff); --sg-pinned-border: color-mix(in oklab, #6366f1 24%, transparent); } ``` For per-row styling, target the row's class directly: ```css .sv-grid-pinned-row-top { font-weight: 700; } .sv-grid-pinned-row-bottom { background: #ecfdf5; } ``` Each row also carries `data-pinned-row="top" | "bottom"` and `data-pinned-index="0..N"` so you can paint distinct ranks differently. ## More examples ### Pinned rows (top / bottom) Frozen "Account totals" row at the top + sticky "Page totals" at the bottom that reacts to filters. Right-click any row to pin it. > Live demo: Pinned rows (top / bottom) - https://svgrid.com/demos/107-pinned-rows/ ## Pinned rows and row numbers Pinned rows sit outside the scrolling body, so they survive sorting and paging. Row numbers count the scrolling rows only, which is what makes a pinned total read as a total rather than as row 6. ```svelte ``` ## See also - Demo 108: Pinned rows (engine prop) - Demo 107: Pinned rows (stacked-grids user-land pattern) - `api.getDisplayedRows()` - drives filter-aware page totals. --- SvGrid is the Svelte 5 data grid (`npm install @svgrid/grid`, MIT). This page: https://svgrid.com/docs/help/rows/row-pinning/ . All docs: https://svgrid.com/llms.txt