{"id":22012390,"url":"https://github.com/nikitaeverywhere/react-xmasonry","last_synced_at":"2025-07-08T03:37:02.610Z","repository":{"id":52214940,"uuid":"84595774","full_name":"nikitaeverywhere/react-xmasonry","owner":"nikitaeverywhere","description":"Simple, minimalistic and featured native masonry layout for React JS.","archived":false,"fork":false,"pushed_at":"2022-08-08T13:44:33.000Z","size":1133,"stargazers_count":90,"open_issues_count":4,"forks_count":12,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-11-28T19:52:21.600Z","etag":null,"topics":["layout","masonry","masonry-grid","masonry-layout","masonry-plugin","react","react-component","react-components","reactjs"],"latest_commit_sha":null,"homepage":"https://zitros.github.io/react-xmasonry","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nikitaeverywhere.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-03-10T19:54:03.000Z","updated_at":"2024-05-21T14:33:46.000Z","dependencies_parsed_at":"2022-08-13T01:21:56.271Z","dependency_job_id":null,"html_url":"https://github.com/nikitaeverywhere/react-xmasonry","commit_stats":null,"previous_names":["zitros/react-xmasonry"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikitaeverywhere%2Freact-xmasonry","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikitaeverywhere%2Freact-xmasonry/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikitaeverywhere%2Freact-xmasonry/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikitaeverywhere%2Freact-xmasonry/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nikitaeverywhere","download_url":"https://codeload.github.com/nikitaeverywhere/react-xmasonry/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227260752,"owners_count":17754950,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["layout","masonry","masonry-grid","masonry-layout","masonry-plugin","react","react-component","react-components","reactjs"],"created_at":"2024-11-30T03:12:37.619Z","updated_at":"2024-11-30T03:12:38.349Z","avatar_url":"https://github.com/nikitaeverywhere.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# XMasonry: Masonry Layout for React JS\n\n[![npm](https://img.shields.io/npm/v/react-xmasonry.svg)](https://www.npmjs.com/package/react-xmasonry)\n[![Dependencies](https://img.shields.io/badge/dependencies-none-brightgreen.svg)](http://npm.anvaka.com/#/view/2d/react-xmasonry)\n[![Build Status](https://travis-ci.org/ZitRos/react-xmasonry.svg?branch=master)](https://travis-ci.org/ZitRos/react-xmasonry)\n[![npm](https://img.shields.io/npm/dm/react-xmasonry.svg)](https://www.npmjs.com/package/react-xmasonry)\n[![License](https://img.shields.io/github/license/zitros/react-xmasonry.svg)](LICENSE)\n[![File Size](http://img.badgesize.io/ZitRos/react-xmasonry/master/dist/index.js)](https://github.com/ZitRos/react-xmasonry/blob/master/dist/index.js)\n[![File Size (GZip)](http://img.badgesize.io/ZitRos/react-xmasonry/master/dist/index.js?compression=gzip)](https://github.com/ZitRos/react-xmasonry/blob/master/dist/index.js)\n[![GitHub](https://img.shields.io/github/stars/zitros/react-xmasonry.svg?style=social\u0026label=Star)](https://github.com/ZitRos/react-xmasonry)\n\nResponsive, minimalistic and full-featured __native__ masonry layout (grid) for React JS.\n\nFeatures\n--------\n\n+ Native masonry layout implementation for React JS with no dependencies.\n+ Minimalistic by design.\n+ Responsive, mobile-friendly approach (so there is no \"fixed block width in pixels\" option).\n+ Configurable width of blocks (in columns) and width of columns (targeting width in pixels), maximum number of columns, centering, etc.\n+ Fully customizable using CSS. Put animations and transitions you like using `.xmasonry` and `.xblock` selectors.\n+ Works with server rendering.\n\n[Demo](https://zitros.github.io/react-xmasonry)\n-----------------------------------------------\n\nCheck the XMasonry [demos page](https://zitros.github.io/react-xmasonry). You can also see the\n[notes application](https://zitros.github.io/easy-local-notes/) made with `react-xmasonry`. \nPlay with [this code pen](https://codepen.io/ZitRos/pen/GmrLQB) to see what XMasonry can.\n\nTable of Contents\n---------------\n\n1. [Installation](#installation)\n2. [Basic Usage](#usage)\n3. [Styling](#styling)\n    1. [Animations \u0026 Transitions](#animations-and-transitions)\n    2. [Server Rendering Note](#server-rendering-note)\n4. [Configuring Components](#configuring-components)\n    1. [\u0026lt;XMasonry\u0026gt; Properties](#xmasonry-component-properties)\n    2. [\u0026lt;XBlock\u0026gt; Properties](#xblock-component-properties)\n    3. [Accessing \u0026lt;XMasonry\u0026gt; by Reference](#accessing-xmasonry-by-reference)\n5. [XMasonry Under the Hood](#xmasonry-under-the-hood)\n6. [License](#license)\n\nInstallation\n------------\n\n```bash\nnpm install react-xmasonry --save-dev\n```\n\nOr, if you use the old-style `\u003cscript\u003e` tag or need an UMD module for demos, use this:\n\n```html\n\u003cscript type=\"text/javascript\" src=\"https://unpkg.com/react-xmasonry/dist/index.js\"\u003e\u003c/script\u003e\n```\n\nHaving trouble installing [react-xmasonry](https://www.npmjs.com/package/react-xmasonry)? \nCheck [this issue](https://github.com/ZitRos/react-xmasonry/issues/1) or \n[open](https://github.com/ZitRos/react-xmasonry/issues) a new one if you still\nstruggling.\n\nUsage\n-----\n\nImport `XMasonry` and `XBlock` components:\n\n```js\nimport { XMasonry, XBlock } from \"react-xmasonry\"; // Imports precompiled bundle\n```\n\nThe simplest layout using JSX and some styling may look like the following:\n\n```jsx\nrender () {\n    return \u003cXMasonry\u003e\n        \u003cXBlock\u003e\n            \u003cdiv className=\"card\"\u003e\n                \u003ch1\u003eSimple Card\u003c/h1\u003e\n                \u003cp\u003eAny text!\u003c/p\u003e\n            \u003c/div\u003e\n        \u003c/XBlock\u003e\n        \u003cXBlock width={ 2 }\u003e\n            \u003cdiv className=\"card\"\u003e\n                \u003ch1\u003eWider card\u003c/h1\u003e\n                \u003cp\u003eAny text!\u003c/p\u003e\n            \u003c/div\u003e\n        \u003c/XBlock\u003e\n    \u003c/XMasonry\u003e\n}\n```\n\nThere is no more JavaScript than positioning and sizing! Use any CSS to make animations and \ntransitions you like (`.xmasonry` and `.xblock` selectors). And all the further magic XMasonry will \ndo for you. See the [demos page](https://zitros.github.io/react-xmasonry) sources\n[here](https://github.com/ZitRos/react-xmasonry/blob/master/docs/jsx/CardsDemo.jsx).\n \nStyling\n-------\n\n### Animations and Transitions\n\nIf you want to put transitions/animations on XMasonry, using the `.xmasonry` and `.xblock` \nselectors. For example:\n\n```css\n@keyframes comeIn {\n    0% { transform: scale(0) }\n    75% { transform: scale(1.03) }\n    100% { transform: scale(1) }\n}\n\n.xmasonry .xblock {\n    animation: comeIn ease 0.5s;\n    animation-iteration-count: 1;\n    transition: left .3s ease, top .3s ease;\n}\n\n.card {\n    margin: 7px;\n    padding: 5px;\n    border-radius: 3px;\n    box-shadow: 0 1px 3px darkgray;\n}\n```\n\nWarning: do not apply any display/positioning/margin styles to `.xblock` selector. Instead, create a \nchild element to XBlock, for example, `.card`, and put any styles you need to it. XBlock's \ndimensions are used in calculations and any styling like adding margins may create an unwanted \nresult. \n\nWarning: do not stick XBlock's content styling to `.xblock` selector. Use `.xmasonry` instead. See\nhow [XMasonry works](#xmasonry-under-the-hood) to understand why: the `.xblock` class is applied\nonly **after** the content measurements are done.\n\n### Server-Side Rendering\n\nXMasonry, being rendered on the server ([renderToStaticMarkup](https://facebook.github.io/react/docs/react-dom-server)),\nwill be unable to detect content heights due server rendering algorithm limitations. \nNevertheless, rendering on the server is possible and won't affect anything (like SEO) but the \nconsistent view with the client-rendered result. To make even this behavior configurable, XMasonry,\nwhen triggered to render contents on the server, puts additional `.xmasonry-static` and\n`.xblock-static` classes respectively, as well as changes some styles to make each XBlock render as\na static-positioned block (by default). You can apply additional styles to this selector to make the \nserver-rendered result look more consistent with the client's one, for example:\n\n```css\n.xmasonry-static {\n    text-align: center;\n    overflow: auto;\n}\n\n.xblock-static {\n    float: left;\n    text-align: left;\n}\n```\n\nYou can disable SSR by using the following environment variable passed to your renderer:\n\n```bash\nREACT_XMASONRY_SSR_ENABLED=false\n```\n\nConfiguring Components\n----------------------\n\nThere are several properties you can assign to `XMasonry` and `XBlock` components.\n\n### `\u003cXMasonry\u003e` Component Properties\n\n| Property | Default | Description |\n|---|---|---|\n| `center` | `true` | A `boolean` value determining whether nested `\u003cXBlock\u003e`s should be centered if there are some empty columns left. |\n| `maxColumns` | `Infinity` | A `number` identifying the maximum columns number. |\n| `responsive` | `true` | A `boolean` value determining whether the layout should be responsive to window size changes. |\n| `smartUpdate` | `true` | A `boolean` value indicating whether Smart Updates are enabled. Smart Update is an XMasonry feature that performs silent checks on XMasonry XBlocks sizes and updates the layout when any size changes are detected. These checks work in the next way: when any update on XMasonry happens, Smart Update will schedule sizes check through the 100 ms (default), then, if no sizes changed, through the 200 ms, 400 ms and so on. When any change happens, this procedure repeats, starting from 100 ms check. These checks and updates are highly optimized - use it for your convenience! |\n| `smartUpdateCeil` | `Infinity` | A `number` in milliseconds which determines the maximum size check interval for XMasonry Smart Update. If you are just too lazy to update dynamic layout manually with `update` method, it's okay to set this prop to some value in milliseconds (for example, 1000 ms). After Smart Update checks interval reaches the specified value, it will start looping to continuously perform checks with `smartUpdateCeil` interval of time. All size checks are optimized and does not waste computing power. |\n| `targetBlockWidth` | `300` | A `number` which determines the \"target\" width in pixels of the nested `\u003cXBlock\u003e`s. The layout takes all available space, and determines the number of columns using this value. For example, if container has `600` px of available width and we specify `targetBlockWidth={200}`, we will get exactly `3` columns of `200` px width. It will still be `3` columns if there is `660` pixels available, this time with each column taking `220` px. The simplified expression for number of columns is the following: `Math.max(1, Math.round(containerWidth / targetBlockWidth))`. |\n| `updateOnFontLoad` | `true` | A `boolean` value determining whether the layout should be updated when fonts are loaded. |\n| `updateOnImagesLoad` | `true` | A `boolean` value determining whether the layout should be updated when images finish loading. It normally takes a little while until images are loaded, and this causes incorrect blocks heights calculations at the beginning. This option allows to auto-update grid sizes when images complete loading. If layout contains no images, no handlers will be assigned. |\n\n### `\u003cXBlock\u003e` Component Properties\n\n| Property | Default | Description |\n|---|---|---|\n| `width` | `1` | A `number` which determines nested block width **in columns**. If the number of columns available is less than the specified width, nested block will shrink to fit available space. |\n\n### Accessing `\u003cXMasonry\u003e` by Reference\n\nYou can access `\u003cXMasonry\u003e` component by reference, but do it only if it is necessarily (for example,\nwhen inner content dynamically changes in size):\n\n```jsx\n\u003cXMasonry ref={ (x) =\u003e this.xMasonry = x }\u003e\n    // ...\n\u003c/XMasonry\u003e\n```\n\nNote that all the listed properties of `\u003cXMasonry\u003e` component are **read-only**.\n\n| Ref Property | Type | Description |\n|---|---|---|\n| `columns` | `number` | The number of currently rendered columns. |\n| `container` | `HTMLElement` | The `\u003cdiv\u003e` block containing the layout. |\n| `update` | `function` | Trigger this function to update nested `XBlock`s sizes and positions. It is **safe to trigger this function multiple times**, updates are optimized. Technically, this function will check if any of containers changed its size and re-render XMasonry only if size was changed. |\n\nBy default, XMasonry sniff and automatically update on the next events:\n1. Window size changes, see `responsive` prop.\n2. Font load events, see `updateOnFontLoad` prop.\n3. Image load events, see `updateOnImagesLoad` prop.\n4. Children changes like adding, replacing or deleting children.\n5. After any change in layout happens, see `smartUpdate` prop.\n\nXMasonry Under the Hood\n-----------------------\n\nTechnically, XMasonry component renders 3 times:\n\n1. \"Empty Render\" (ER), when XMasonry just renders its empty container and measures the available width;\n2. \"Invisible Render\" (IR), when XMasonry renders `visibility: hidden` blocks width computed column widths to measure their heights;\n3. And finally \"Actual Render\" (AR), when it renders elements with computed dimensions and positions. The `.xblock` style gets applied here only, so you can put animations on it.\n\nThis stages take around 3-4 frames to appear on the screen (~60ms).\n\nEach time when elements change in masonry layout (images load or animation end, depending on initial\nconfiguration), the XMasonry `update` method is triggered. It goes through rendered elements this \ntime, and looks for any size changes there. Thanks to React, all the DOM updates are optimized here \nand this function is very light to call. You can manually trigger XMasonry `update` function, \nwhenever you need to update the layout. By default, after any change in layout, Smart Update will \nbe performed. Check `smartUpdate` prop description for more information.\n\nOnce the window size gets changed (default behavior), the \"force update\" technique is applied, which\ndo the IR and AR phases again.\n\nLicense\n-------\n\n[MIT](license) © [Nikita Savchenko](https://nikita.tk)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnikitaeverywhere%2Freact-xmasonry","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnikitaeverywhere%2Freact-xmasonry","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnikitaeverywhere%2Freact-xmasonry/lists"}