weighted-grid

Sized by weight. Rendered as native CSS Grid.

Per item and per axis: a relative weight, an exact cols/rows span, or one of each. The grid places items in source order, grows the elastic ones into leftover space, and hands whatever is still empty to a fill component. The JS only decides spans — CSS Grid does the rendering.

▶ Play with the live demo

Use plain CSS Grid when you know the layout up front. Reach for this when the item count is whatever the API returned and you still want it to look deliberate. Not a drag-and-drop library, and not trying to be — want that? Open an issue.

Full history in CHANGELOG.md.

bun add weighted-grid   # npm / pnpm / yarn all fine

import { Grid, GridItem } from "weighted-grid/react";

<Grid nrCols={7}>
  <GridItem weight={4}>hero</GridItem>
  <GridItem>a</GridItem>
  <GridItem>b</GridItem>
  <GridItem>c</GridItem>
</Grid>;

weight works like flexbox flex: how much of the grid does this item get. Equal weights give equal squares.

Three ideas, and you've seen the whole library.

1 · Weight sizes both axes. weight={2} is a 2×2 block. Pin one axis with cols or rows and weight keeps driving the other:

<GridItem weight={4}>elastic on both axes</GridItem>
<GridItem cols={3} weight={2}>3 columns wide, weight sets the height</GridItem>
<GridItem cols={2} rows={2}>strict — never stretches</GridItem>

Elasticity is per axis. Only pinning both makes an item fully rigid.

2 · Leftover space gets absorbed, fairly. Elastic items stretch into the gaps around them, split evenly between the neighbours flanking a gap — never all growth dumped on one side. Cap it globally with stretch={n} on the Grid, or per item.

3 · Whatever's left is yours. Cells nothing could reach are merged into rectangular blocks and handed to fillComponent — one node per block, not one per cell. Skip the prop and they stay empty.

<Grid
  nrCols={12}
  stretch={2}
  fillComponent={(rect) => <Placeholder {...rect} />}
>
  {items.map((item) => (
    <GridItem key={item.id}>{item.label}</GridItem>
  ))}
</Grid>

Prop tables below are generated by type-to-table — re-run bun run docs:props, or it runs automatically on npm publish.

💡 stretch on an item cuts both ways: let a cols-pinned card grow into a gap anyway, or stop one greedy elastic item from eating the whole row.

A preset is just a function — ({ count, nrCols, nrRows }) => Partial<GridItemProps>[] — that hands each item its defaults. Perfect for "here are 40 cards, make it look intentional".

import { masonPreset } from "weighted-grid/presets";

<Grid nrCols={8} preset={masonPreset()}>
  {items.map((item) => (
    <GridItem key={item.id}>{item.label}</GridItem>
  ))}
</Grid>;

• masonPreset(brick = 2) — running-bond brick rows, every other row offset by half a brick.
• organicPreset(seed = 1) — a drifting mosaic of small/medium/large tiles, scaled to nrCols.

They live on the weighted-grid/presets subpath, so a preset you don't import (and its code) never reaches your bundle. Rolling your own is a ten-liner:

import type { PresetFn } from "weighted-grid/presets";

const stripes: PresetFn = ({ count, nrCols }) =>
  Array.from({ length: count }, (_, i) => ({
    weight: i % nrCols < nrCols / 2 ? 2 : 1,
  }));

Keep the function reference stable (module scope, or useCallback) — Grid memoizes on it.

There's no wrap prop, because there doesn't need to be one. Spans clamp to nrCols, so dropping the column count at a breakpoint reflows everything into fewer columns and more rows, flex-wrap style:

<Grid nrCols={isMobile ? 2 : 6}>...</Grid>

Every one of these runs in the live demo — the source is a few lines long and worth a skim.

bun install
bun run test        # bun test
bun run typecheck
bun run build       # vite → dist/
bun run format      # biome check --write
bun run demo:dev    # the demo app in demo/

MIT © jayF0x