# DreamMasonry

> Virtualized masonry grid component for React. Renders only visible items for smooth performance with large lists. Built-in infinite scroll, responsive columns, zero dependencies.

DreamMasonry is a React library for building Pinterest-style masonry layouts that stay fast with 10,000+ items. It virtualizes the grid so only items in/near the viewport are mounted to the DOM.

Key capabilities:
- Virtualized rendering with configurable overscan
- Built-in infinite scroll with threshold and debounce controls
- Responsive column count based on container width
- Float64Array-based layout engine for fast positioning
- Headless hooks (useGrid, usePositioner, useInfiniteScroll) for custom rendering
- Custom scroll container support
- Zero dependencies beyond React 18+
- ~13KB bundle size

Use DreamMasonry when you need a masonry/waterfall/Pinterest-style grid in React and your list is large enough that rendering everything to the DOM would hurt performance. If you only have a small number of items and don't need virtualization, a CSS-only solution like react-masonry-css may be simpler.

## Docs

- [Live demo](https://adioof.github.io/dream-masonry/): Interactive demo with infinite scroll
- [README and API reference](https://github.com/adioof/dream-masonry#readme): Full documentation including props, hooks API, and usage examples
- [npm package](https://www.npmjs.com/package/dream-masonry): Package page with install instructions

## Source

- [Main component](https://github.com/adioof/dream-masonry/blob/main/src/DreamMasonry.tsx): The DreamMasonry component implementation
- [useGrid hook](https://github.com/adioof/dream-masonry/blob/main/src/hooks/use-grid.ts): Headless virtualized grid hook
- [usePositioner hook](https://github.com/adioof/dream-masonry/blob/main/src/hooks/use-positioner.ts): Layout-only hook (no DOM)
- [useInfiniteScroll hook](https://github.com/adioof/dream-masonry/blob/main/src/hooks/use-infinite-scroll.ts): Standalone infinite scroll hook
- [Types](https://github.com/adioof/dream-masonry/blob/main/src/types.ts): TypeScript type definitions and constants