react-xmasonry

Responsive, minimalistic and full-featured native masonry layout (grid) for React JS.

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 targeting 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 like 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 prop.
2. Font load events, see updateOnFontLoad prop.
3. Image load events, see updateOnImagesLoad prop.
4. Children changes like adding, replacing or deleting children.
5. After any change in layout happens, see smartUpdate prop.

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 manually trigger XMasonry update function, whenever you need to update the layout. By default, after any change in layout, Smart Update will be performed. Check smartUpdate prop description for more information.

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

Licence

MIT © Nikita Savchenko