Vue CSS Masonry Component

1.0.3 · maintenance · verified Sun Apr 19

Vue-masonry-css is a Vue.js component that provides a masonry layout powered by CSS, prioritizing fast rendering and optimal utilization of Vue's Virtual DOM. It is dependency-free, specifically avoiding external libraries like jQuery or traditional JavaScript-based masonry solutions (e.g., DeSandro Masonry) which often introduce performance overhead through double-rendering. The current stable version is 1.0.3, and it appears to follow a slow, stable release cadence given its nature as a lightweight, dependency-free UI component. Key differentiators include its responsive-by-default behavior, compatibility with IE10+ (including IE9, though this might be an outdated claim), and seamless integration with existing CSS animations. It achieves its layout using plain divs and a touch of flexbox, offering a simple interface to define columns and gutter sizes based on responsive breakpoints. Notable limitations include its inability to handle elements with varying widths within a single column and its intentional omission of height-based sorting to maintain high rendering performance.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'use') at Function.Vue.use
```
cause The `Vue` global object or imported `Vue` instance was not properly initialized or available before calling `Vue.use(VueMasonry)`.

fix Ensure `import Vue from 'vue'` is present at the top of your main application file and that Vue is correctly initialized before `Vue.use()` is called, especially when using module bundlers.
```
[Vue warn]: Unknown custom element: <masonry> - did you register the component correctly?
```
cause The `<masonry>` component was not globally registered via `Vue.use(VueMasonry)` or was not imported and registered locally in the component where it's being used.

fix Verify that `import VueMasonry from 'vue-masonry-css'` and `Vue.use(VueMasonry)` are executed in your application's entry point (e.g., `main.js` or `app.js`).
```
[Vue warn]: Invalid prop: type check failed for prop "cols". Expected Number, got Object
```
cause The `cols` or `gutter` prop was provided with an object (for responsive breakpoints) but was not bound using `v-bind` or its shorthand `:`.

fix Change `cols="{ default: 4, 700: 2 }"` to `:cols="{ default: 4, 700: 2 }"` in your template. Similarly, apply this for the `gutter` prop when using an object.

Warnings

breaking This package is designed for Vue 2 applications and is not compatible with Vue 3's composition API or instance creation API (`createApp`).
Fix: For Vue 3 projects, seek an alternative masonry component or consider migrating your application to Vue 2 if this component is critical. Attempting to use `Vue.use()` with `createApp` will result in errors.
gotcha The component does not support items with varying widths within a single column. All items are expected to occupy the full width of their respective columns.
Fix: Ensure all items rendered within the `<masonry>` component have consistent widths. If your layout requires variable-width items, consider a different masonry library that explicitly supports this feature.
gotcha This library intentionally omits height-based sorting of items to maintain rendering performance. Items are ordered based on their input sequence within each column.
Fix: If strict height-based sorting is a requirement for your design, this component may not be suitable. You would need to pre-sort your `items` array before passing it to the component, or explore alternative solutions that prioritize height-based placement.
gotcha When defining responsive breakpoints for `cols` or `gutter` using an object, the attributes must be bound using `v-bind` or its shorthand `:`.
Fix: Instead of `cols="{default: 4, 700: 2}"`, use `:cols="{default: 4, 700: 2}"`. Failing to bind the object will result in the object being treated as a string literal, or prop type validation errors.

Install

npm install vue-masonry-css npm
yarn add vue-masonry-css yarn
pnpm add vue-masonry-css pnpm

Imports

VueMasonry
wrong:
```
import { VueMasonry } from 'vue-masonry-css'
```
correct:
```
import VueMasonry from 'vue-masonry-css'
```
This package exports a default Vue plugin object. It should be imported as a default export and then passed to `Vue.use()` for global component registration in Vue 2 applications.
Vue.use(VueMasonry)
wrong:
```
app.use(VueMasonry)
```
correct:
```
Vue.use(VueMasonry)
```
For Vue 2 applications, the plugin is registered globally using `Vue.use()`. This makes the `<masonry>` component available throughout your application. This method is incompatible with Vue 3's `app.use()`.

Quickstart

This quickstart demonstrates how to import and globally register the `vue-masonry-css` plugin, then use the `<masonry>` component in a Vue 2 template with responsive column and gutter configurations.

import Vue from 'vue';
import VueMasonry from 'vue-masonry-css';

Vue.use(VueMasonry);

new Vue({
  el: '#app',
  data: {
    items: Array.from({ length: 15 }, (_, i) => ({ id: i + 1, height: `${Math.floor(Math.random() * 100) + 100}px` }))
  },
  template: `
    <div id="app">
      <h1>My Masonry Layout</h1>
      <masonry
        :cols="{default: 4, 1000: 3, 700: 2, 400: 1}"
        :gutter="{default: '30px', 700: '15px'}"
      >
        <div 
          v-for="(item, index) in items" 
          :key="item.id" 
          :style="{ height: item.height, background: '#f0f0f0', padding: '15px', border: '1px solid #ddd', marginBottom: '30px' }"
        >
          Item: {{ index + 1 }}
        </div>
      </masonry>
    </div>
  `
});

view raw JSON →