Simple & featured native masonry layout implementation for React JS

react-xmasonry

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

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

Features

• Native masonry layout implementation for React JS with no dependencies.
• Minimalistic by design.
• Responsive, mobile-friendly approach (so there is no "fixed block width in pixels" option).
• Configurable width of blocks (in columns) and width of columns (targeting width in pixels), maximum number of columns, centering, etc.
• Fully customizable using CSS. Put animations and transitions you like using .xmasonry and .xblock selectors.
• Works with server rendering.

Installation

npm install react-xmasonry --save-dev

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

<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"; // Imports JSX plain sources
import { XMasonry, XBlock } from "react-xmasonry/dist/index.js"; // Imports precompiled bundle

The simplest layout using JSX and some styling may look like the following:

render () {
    return <XMasonry>
        <XBlock>
            <div className="card">
                <h1>Simple Card</h1>
                <p>Any text!</p>
            </div>
        </XBlock>
        <XBlock width={ 2 }>
            <div className="card">
                <h1>Wider card</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). And all the further magic XMasonry will
do for you. See the demos page sources
here.

Styling

Animations and Transitions

If you want to put transitions/animations on XMasonry, using the .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;
}

Warning: do not apply any display/positioning/margin styles to .xblock selector. Instead, create a
child element to XBlock, for example, .card, and put any styles you need to it. XBlock's
dimensions are used in calculations and any styling like adding margins may create an unwanted
result.

Warning: do not stick XBlock's content styling to .xblock selector. Use .xmasonry instead. See
how XMasonry works to understand why: the .xblock class is applied
only after the content measurements are done.

Server Rendering Note

XMasonry, being rendered on the server (renderToStaticMarkup),
will be unable to detect content heights due server rendering algorithm limitations.
Nevertheless, rendering on the server is possible and won't affect anything (like SEO) but the
consistent view with the client-rendered result. To make even this behavior configurable, XMasonry,
when triggered to render contents on the server, puts additional .xmasonry-static and
.xblock-static classes respectively, as well as changes some styles to make each XBlock render as
a static-positioned block (by default). You can apply additional styles to this selector to make the
server-rendered result look more consistent with the client's one, for example:

.xmasonry-static {
    text-align: center;
    overflow: auto;
}

.xblock-static {
    float: left;
    text-align: left;
}

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.

GitHub