masonic

---

---

npm i masonic

A performant and versatile virtualized masonry grid for React based on Brian Vaughn's [react-virtualized](https://github.com/bvaughn/react-virtualized) and further inspired by [react-window](https://github.com/bvaughn/react-window). Using Masonic, you're not just getting a component. You're getting the implementation details, as well, meaning advanced usage requiring little code is possible. ## Features - [x] **Easy to use** It takes two minutes to start creating your own masonry grid with this component. [For real, check out the demo on **CodeSandbox**](https://codesandbox.io/s/0oyxozv75v). - [x] **Blazing™ fast** This component can seamlessly render tens of thousands of grid cells without lag via its virtualization algorithm and underlying [data structures](https://www.scaler.com/topics/data-structures/what-is-data-structure/). For example, it uses a [red black interval tree](https://www.geeksforgeeks.org/interval-tree/) to determine which cells to render, based upon the scroll position and size of the window the grid is rendered in. Interval trees have `O(log n + m)` search performance . - [x] **TypeScript** Intellisense and type safety mean fewer bugs in your implementation. - [x] **Versatility** All of [``](#masonry)'s implementation details (hooks, utilities) are exported, so you're not locked into to the default implementation. As you advance, it will be useful to have access to those internals. It's also possible to kick the virtualization out of the equation by providing an `Infinity` value to the `overscanBy` prop, though this would be a terrible idea for large lists. - [x] **Autosizing** The default [``](#masonry) component will automatically resize itself and its items if the content of the grid cells changes or resizes. For example, when an image lazily loads this component will automatically do the work of recalculating the size of that grid cell. That said, you should try to premeasure things (including images) as often as possible in order to achieve the best user experience. ## Quick Start [Check out the demo on **CodeSandbox**](https://codesandbox.io/s/0oyxozv75v) ```jsx harmony import * as React from "react"; import { Masonry } from "masonic"; let i = 0; const items = Array.from(Array(5000), () => ({ id: i++ })); const EasyMasonryComponent = (props) => ( ); const MasonryCard = ({ index, data: { id }, width }) => (

ID: {id}

); ``` ## Documentation ### Components | Component | Description | | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [``](#masonry) | A "batteries included" masonry grid which includes all of the implementation details below. This component is the easiest way to get off and running in your app, before switching to more advanced implementations, if necessary. It will change its column count to fit its container's width and will decide how many rows to render based upon the height of the browser `window`. | | [``](#masonryscroller) | A heavily-optimized component that updates [`useMasonry()`](#usemasonryoptions) when the scroll position of the browser `window` changes. This bare-metal component is used by [``](#masonry) above. | | [``](#list) | This is just a single-column [``](#masonry) component with no `columnGutter` prop, only `rowGutter`. | ### Hooks | Hook | Description | | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`useMasonry()`](#usemasonryoptions) | This hook handles the render phases of the masonry layout and returns the grid as a React element. | | [`usePositioner()`](#usepositioneroptions-deps) | This hook creates the grid cell positioner and cache required by [`useMasonry()`](#usemasonryoptions). This is the meat of the grid's layout algorithm, determining which cells to render at a given scroll position, as well as where to place new items in the grid. | | [`useResizeObserver()`](#useresizeobserverpositioner) | Creates a resize observer that forces updates to the grid when mutations are made to the grid cells affecting their size. | | [`useContainerPosition()`](#usecontainerpositionelementref-deps) | A hook for measuring the width of the grid container, as well as its distance from the top of the document. These values are necessary to correctly calculate the number/width of columns to render, as well as the number of rows to render. | | [`useScroller()`](#usescrolleroffset-fps) | A hook for tracking whether the `window` is currently being scrolled and it's scroll position on the y-axis. These values are used for determining which grid cells to render and when to add styles to the grid container that maximize scroll performance. | | [`useScrollToIndex()`](#usescrolltoindexpositioner-options) | A hook that creates a callback for scrolling to a specific index in the "items" array. | | [`useInfiniteLoader()`](#useinfiniteloaderloadmoreitems-options) | A utility hook for seamlessly adding infinite scroll behavior to the [`useMasonry()`](#usemasonryoptions) hook. This hook invokes a callback each time the last rendered index surpasses the total number of items in your items array or the number defined in the `totalItems` option of this hook. | ### Utilities | Utility | Description | | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`createPositioner()`](#createpositionercolumncount-columnwidth-columngutter-rowgutter) | Creates a cell positioner for the [`useMasonry()`](#usemasonryoptions) hook. The [`usePositioner()`](#usepositioneroptions-deps) hook uses this utility under the hood. | | [`createResizeObserver()`](#createresizeobserverpositioner-updater) | Creates a resize observer that fires an `updater` callback whenever the height of one or many cells change. The [`useResizeObserver()`](#useresizeobserverpositioner) hook is using this under the hood. | ### Recipes - [Add infinite scrolling behavior to your Masonry component.](https://codesandbox.io/s/useinfiniteloader-example-vn30p?file=/src/index.js) - [Cells don't resize once they're measured? Build a Masonry grid without the resize observer.](https://codesandbox.io/s/usemasonry-example-3pcg9?file=/src/index.js) - [Reset `` layout when switching between routes within the same component.](https://codesandbox.io/s/masonic-w-react-router-example-2b5f9?file=/src/index.js) - [Do the same with an advanced custom implementation using the `usePositioner()` hook.](https://codesandbox.io/s/masonic-w-react-router-and-advanced-config-example-8em42?file=/src/index.js) - [Render a Masonry component relative to a scrollable HTML element rather than the browser `window`.](https://codesandbox.io/s/masonic-inside-of-a-scrollable-div-example-k9l6c?file=/src/index.js) - [Add an `isScrolling` prop to cells](https://codesandbox.io/s/usemasonry-example-3pcg9?file=/src/index.js) --- ### <Masonry> An autosizing masonry grid that only renders items currently visible in the browser `window`. This component will change its column count to fit its container's width and will decide how many rows to render based upon the height of the browser `window`. To facilitate this, it uses [`useMasonry()`](#usemasonryoptions), [`usePositioner()`](#usepositioneroptions-deps), [`useResizeObserver()`](#useresizeobserverpositioner), [`useContainerPosition()`](#usecontainerpositionelementref-deps), and [`useScroller()`](#usescrolleroffset-fps) under the hood. This is the "batteries included" option. It's the easiest way to get off and running with your app and a great stepping stone to more advanced implementations, should you need them. [Check out an example on **CodeSandbox**](https://codesandbox.io/s/0oyxozv75v) ```jsx harmony import * as React from "react"; import { Masonry } from "masonic"; let i = 0; const items = Array.from(Array(5000), () => ({ id: i++ })); const EasyMasonryComponent = (props) => ( ); const MasonryCard = ({ index, data: { id }, width }) => (

ID: {id}

);