Sticky-header viewport

Prop enableStickyHeader — engine behaviour, default false.

Guide

When to use it

Keep the header (and filter row) visible while the body scrolls — without the table growing taller and taller as the page size grows.

How it works

Caps the scroll box to a bounded height and scrolls the body under a sticky header + filter row. Height is --bst-max-height (default 440px), or set it: boolean | { maxHeight, maxRows }.

<BstTableMui data={rows} columns={columns} getRowId={(r) => r.id}
  enableStickyHeader={{ maxRows: 12 }} />

Gotchas

• Skipped when enableVirtualization is on — virtualization already bounds the scroll box, so the two never stack.
• Always available in the settings sheet ("Rows") for end-users to switch on.

Live example

Example source

import React from 'react'
import { BstTableMui } from '@bloomskill/table-mui'
import type { BstTableColumn } from '@bloomskill/table-engine'
import '@bloomskill/table-engine/styles.css'
type Row = { id: string; name: string; team: string; role: string; score: number }
const seed: Row[] = [
  { id: '1', name: 'Ada Lovelace',    team: 'Platform', role: 'Engineer',  score: 92 },
  { id: '2', name: 'Alan Turing',     team: 'Research', role: 'Scientist', score: 88 },
  { id: '3', name: 'Grace Hopper',    team: 'Platform', role: 'Engineer',  score: 95 },
  { id: '4', name: 'Katherine J.',    team: 'Research', role: 'Analyst',   score: 90 },
  { id: '5', name: 'Edsger Dijkstra', team: 'Platform', role: 'Architect', score: 84 },
]
const columns: BstTableColumn<Row>[] = [
  { id: 'name', accessorKey: 'name', header: 'Name' },
  { id: 'team', accessorKey: 'team', header: 'Team' },
  { id: 'role', accessorKey: 'role', header: 'Role' },
  { id: 'score', accessorKey: 'score', header: 'Score', sortFn: 'basic' },
]
const many: Row[] = Array.from({ length: 24 }, (_, i) => ({ ...seed[i % 5], id: String(i + 1) }))
export default function App() {
  return (
    <BstTableMui data={many} columns={columns} getRowId={(r) => r.id}
      enableStickyHeader={{ maxRows: 7 }} pagination={false} />
  )
}

Loading live example…

Overview

Layer	enable* (engine, resolved in useBstTable)
Type	boolean | {maxHeight,maxRows}
Default	false
Maps to	custom render — caps the scroll box to a bounded height (--bst-max-height; default 440px, or maxHeight px/CSS length, or maxRows × row estimate) so the body scrolls under a sticky header + filter row instead of the table growing taller as the page size grows (resolveStickyHeader pure helper; class bst-sticky-header). Row virtualization already does this, so the standalone class is skipped when enableVirtualization is on (the two never stack). In settings ("Rows", always shown so an end-user can switch it on)
Status	✅ done
Since	v0.40.0
Settings sheet	Rows

Sticky-header viewport — cap the scrollable body to a bounded height so the rows scroll inside the grid under a header (and per-column filter row) that stays pinned, instead of the whole table growing taller as the page size grows. true uses a default height; pass an object to size it by pixels ({ maxHeight }) or by a number of visible rows ({ maxRows }). An object implies enabled. Opt-in. Default: false. Row virtualization (enableVirtualization) already includes this behaviour — it also caps the body and sticks the header — so this is the same viewport without row windowing, for small / medium grids. The height is overridable via styles.root.

Enable it

<BstTableMui
  data={rows}
  columns={columns}
  enableStickyHeader={/* boolean | {maxHeight,maxRows} */}
/>

Swap BstTableMui for BstTableShadcn (and the CSS import) for the shadcn skin — same props.

Behavior & interactions

• Caps the scroll box to a bounded height (default 440px; size it with { maxHeight } or { maxRows }) so the body scrolls under a pinned header + filter row, instead of the table growing taller with the page size. Row virtualization already does this, so the engine skips the standalone class when enableVirtualization is on — the two never stack.

Spec coverage

Spec codes (A1, C2, X8, …) are Bst-Table's internal requirement IDs from the capability matrix; P0–P2 mark the delivery phase. They are traceability tags, not part of the public API.

• G3 · Auto layout — ✅ built. fixed layout + total-size + fitColumns fit-to-viewport
• G4 · Responsive — ✅ built. v0.22.0 — enableResponsive + meta.responsivePriority (hide low-priority when narrow)