Column Sizing
Three sizing modes — fixed (exact pixels), flex (proportional fill), and auto (equal fill). Mix and match in a single grid, and optionally let the grid auto-resize columns to fill its container.
Sizing Modes
fixed columns hold their width exactly. flex columns divide the remaining space according to flexGrow — a value of 2 claims twice as much as 1. auto columns share remaining space equally.
Three sizing modes
Every column uses one of three modes, set via the sizing property:
-
'fixed'— the column takes exactlywidthpixels. It never grows or shrinks. This is the default when you setwidthwithout an explicitsizing. -
'flex'— the column claims its proportional share of the remaining space after fixed columns are placed. Control the ratio withflexGrow: a column withflexGrow: 2gets twice as much space as one withflexGrow: 1. SetminWidthto prevent it from collapsing below a usable size. -
'auto'— like flex, but all auto columns share remaining space equally.
Why rows use CSS Grid, not flex
Each row is a CSS Grid with grid-template-columns driven by a shared
--gc-row-template CSS variable. Flex rows consult content-based min sizes
for nested flex containers, which causes header and body cells to drift apart at fractional
widths. CSS Grid distributes space without consulting content size, keeping header and body
cells pixel-aligned at every column width.
Resize converts flex to fixed
When a user drags the resize handle on a flex column, the column automatically converts
to 'fixed' sizing at the dragged width. Once the user supplies a concrete pixel
width, proportional distribution no longer applies. The columnResized output
fires with { key, newWidth, prevWidth, final: true } when the drag ends.
Dragging the resize handle on a flex column converts it to 'fixed'
at the dragged width — once the user picks a concrete px width, proportional distribution
no longer applies to that column.
Size Columns to Fit
autoSizeColumns: true resizes all eligible columns so their combined width exactly fills the grid — no horizontal scrollbar. It re-runs automatically on container resize and when columns are shown or hidden. Mark a column with suppressSizeToFit: true to exclude it from redistribution.
fitGridWidth strategy
autoSizeStrategy: { type: 'fitGridWidth' } scales all eligible columns so their
combined width exactly fills the grid — no horizontal scrollbar. It re-runs automatically on
container resize and when columns are shown or hidden. Mark a column with
suppressSizeToFit: true to keep its exact width out of the redistribution.
Auto-Size to Content
fitCellContents sizes each column to its natural content width after first data load — Email and Role get wider, Dept and # stay narrow. suppressAutoSize: true on the # column keeps it untouched. scaleUpToFitGridWidth then fills leftover space.
fitCellContents strategy
{ type: 'fitCellContents' } measures each column's natural content width after the
first data load and sizes the column to it. Add scaleUpToFitGridWidth: true to
distribute any leftover space afterwards. suppressAutoSize: true excludes a column
from content measurement; suppressSizeToFit: true excludes it from the scale-up pass.
Re-trigger imperatively any time with grid.autoSizeColumns().
Dynamic Grid Height
height: 'auto' expands the grid to fit all rows — the page scrolls, not the grid. A fixed number (px) gives the grid an internal scrollbar. Switch between modes at runtime without remounting.
Three height modes
The height config property accepts a number (px), a CSS string, or the special value 'auto':
-
'auto'— the grid expands vertically to fit all loaded rows. There is no internal scroll; the page itself scrolls. Best for short lists where you want the full table visible at once. Sticky group headers and inner-scroll grouping do not work in auto-height mode — there is no overflow scroll to trigger them. -
Number (e.g.
400) — fixed pixel height. Rows that overflow scroll internally. Most flexible: sticky columns, grouping, virtual scroll, and live updates all work correctly. -
CSS string (e.g.
'100%') — fills the parent container. The parent must have a defined height. Combine with a resizable wrapper for responsive layouts.
Responsive Container
Set height: '100%' and the grid fills its parent. Combined with autoSizeColumns: true, a ResizeObserver inside the grid automatically refits column widths whenever the container changes size — drag the slider to see it live.
320pxFilling a resizable parent
height: '100%' makes the grid track its parent's height — the parent must have a
concrete height. A ResizeObserver inside the grid re-runs the active
autoSizeStrategy whenever the container changes size, so column widths stay fitted
during window resizes and layout changes.
Sizing options
| Property | Type | Default | Description |
|---|---|---|---|
| column.sizing | 'fixed' | 'flex' | 'auto' | 'fixed' | fixed holds width px exactly; flex shares leftover space by flexGrow; auto shares it equally. |
| column.width | number | — | Pixel width for fixed columns; starting width before an auto-size strategy runs. |
| column.flexGrow | number | 1 | Proportional share for flex columns — 2 claims twice the space of 1. |
| column.minWidth | number | 50 | Lower bound in px — stops flex/auto columns collapsing below a usable size. |
| config.autoSizeStrategy | { type: 'fitGridWidth' | 'fitCellContents', scaleUpToFitGridWidth? } | — | Fill the grid width, or size to measured content (optionally scaling up afterwards). Re-runs on container resize and column show/hide. |
| column.suppressSizeToFit | boolean | false | Excludes the column from width redistribution (fit / scale-up passes). |
| column.suppressAutoSize | boolean | false | Excludes the column from fitCellContents measurement. |
| grid.autoSizeColumns() | () => void | — | Imperative re-run of the active auto-size strategy. |