{"id":12526,"library":"vue-masonry-css","title":"Vue CSS Masonry Component","description":"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.","status":"maintenance","version":"1.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/paulcollett/vue-masonry-css","tags":["javascript","vue","vue.js","masonry","masonary","component","css"],"install":[{"cmd":"npm install vue-masonry-css","lang":"bash","label":"npm"},{"cmd":"yarn add vue-masonry-css","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-masonry-css","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { VueMasonry } from 'vue-masonry-css'","symbol":"VueMasonry","correct":"import VueMasonry from 'vue-masonry-css'"},{"note":"For Vue 2 applications, the plugin is registered globally using `Vue.use()`. This makes the `` component available throughout your application. This method is incompatible with Vue 3's `app.use()`.","wrong":"app.use(VueMasonry)","symbol":"Vue.use(VueMasonry)","correct":"Vue.use(VueMasonry)"}],"quickstart":{"code":"import Vue from 'vue';\nimport VueMasonry from 'vue-masonry-css';\n\nVue.use(VueMasonry);\n\nnew Vue({\n el: '#app',\n data: {\n items: Array.from({ length: 15 }, (_, i) => ({ id: i + 1, height: `${Math.floor(Math.random() * 100) + 100}px` }))\n },\n template: `\n
\n

My Masonry Layout

\n \n
\n Item: {{ index + 1 }}\n
\n \n
\n `\n});","lang":"javascript","description":"This quickstart demonstrates how to import and globally register the `vue-masonry-css` plugin, then use the `` component in a Vue 2 template with responsive column and gutter configurations."},"warnings":[{"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.","message":"This package is designed for Vue 2 applications and is not compatible with Vue 3's composition API or instance creation API (`createApp`).","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Ensure all items rendered within the `` component have consistent widths. If your layout requires variable-width items, consider a different masonry library that explicitly supports this feature.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"This library intentionally omits height-based sorting of items to maintain rendering performance. Items are ordered based on their input sequence within each column.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"When defining responsive breakpoints for `cols` or `gutter` using an object, the attributes must be bound using `v-bind` or its shorthand `:`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The `Vue` global object or imported `Vue` instance was not properly initialized or available before calling `Vue.use(VueMasonry)`.","error":"TypeError: Cannot read properties of undefined (reading 'use') at Function.Vue.use"},{"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`).","cause":"The `` component was not globally registered via `Vue.use(VueMasonry)` or was not imported and registered locally in the component where it's being used.","error":"[Vue warn]: Unknown custom element: - did you register the component correctly?"},{"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.","cause":"The `cols` or `gutter` prop was provided with an object (for responsive breakpoints) but was not bound using `v-bind` or its shorthand `:`.","error":"[Vue warn]: Invalid prop: type check failed for prop \"cols\". Expected Number, got Object"}],"ecosystem":"npm"}