react-xmasonry

Responsive, minimalistic and featured native masonry layout for React JS.

General Features

• React JS native masonry layout implementation with no dependencies.
• Minimalistic design and simple use case.
• Ability to control blocks width (in columns) and columns width.
• Responsive, mobile-friendly approach (so there is no "fixed block width" option).
• Fully customizable: use CSS animations and transitions you wish (use .xmasonry and .xblock selectors).

Demo

Check the XMasonry demos page. You can also see the notes application made with react-xmasonry. Play with this code pen to see what XMasonry can.

Installation

npm install react-xmasonry --save-dev

Or, if you use the old-style <script> tag or need UMD module for demos, use the next:

<script type="text/javascript" src="https://unpkg.com/react-xmasonry/dist/index.js"></script>

Having trouble installing react-xmasonry? Check this issue or open a new one if you still struggling.

Usage

Import XMasonry and XBlock components:

import { XMasonry, XBlock } from "react-xmasonry";

The simplest layout using JSX and a little styling may look as following:

render () {
    const data = [1, 2, 3, 4, 5];
    return <XMasonry>{ data.map(number =>
        <XBlock key={ number }>
            <div className="card">
                <h1>Card #{ number }</h1>
                <p>Any text!</p>
            </div>
        </XBlock>
    )}</XMasonry>
}

There is no more JavaScript than positioning and sizing! Use any CSS to make animations and transitions you like (.xmasonry and .xblock selectors), for example:

@keyframes comeIn {
    0% { transform: scale(0) }
    75% { transform: scale(1.03) }
    100% { transform: scale(1) }
}

.xmasonry .xblock {
    animation: comeIn ease 0.5s;
    animation-iteration-count: 1;
    transition: left .3s ease, top .3s ease;
}

.card {
    margin: 7px;
    padding: 5px;
    border-radius: 3px;
    box-shadow: 0 1px 3px darkgray;
}

And all the further magic XMasonry will do for you. See the demos page sources here.

Configuring Components

There are several properties you can assign to XMasonry and XBlock components.

<XMasonry> Component Properties

<XBlock> Component Properties

Accessing <XMasonry> by Reference

You can access <XMasonry> component by reference, but do it only if it is necessarily (for example, when inner content dynamically changes in size):

<XMasonry ref={ (x) => this.xMasonry = x }>
    // ...
</XMasonry>

Note that all the listed properties of <XMasonry> component are read-only.

By default, XMasonry sniff and automatically update on the next events:

1. Window size changes, see responsive property.
2. Font load events, see ``updateOnFontLoad` property.
3. Image load events, see updateOnImagesLoad property.
4. Children changes like adding, replacing or deleting children.

XMasonry Under the Hood

Technically, XMasonry component renders 3 times:

1. "Empty Render" (ER), when XMasonry just renders its empty container and measures the available width;
2. "Invisible Render" (IR), when XMasonry renders visibility: hidden blocks width computed column widths to measure their heights;
3. 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.

This stages take around 3-4 frames to appear on the screen (~60ms).

Each time when elements change in masonry layout (images load or animation end, depending on initial configuration), the XMasonry update method is triggered. It goes through rendered elements this time, and looks for any size changes there. Thanks to React, all the DOM updates are optimized here and this function is very light to call. You can trigger XMasonry update on your own, whenever you need to update the layout.

Once the window size gets changed (default behavior), the "force update" technique is applied, which do the IR and AR phases again.