Vue 3 Masonry Layout Component

Common errors

• [Vue warn]: Failed to resolve component: masonry

  cause The `<masonry>` component has not been globally registered with the Vue application instance.
  fix Ensure you call `app.use(masonry)` in your main application entry point (`main.ts` or `main.js`) after creating your Vue app instance.

• Items within <masonry> are not displaying in a proper grid layout; instead, they appear stacked vertically or improperly positioned when using slots.

  cause The component is failing to correctly detect and arrange child elements passed through a default slot, often due to how Vue renders slot content.
  fix Add the prop `:resolve-slot="true"` to your `<masonry>` component if its children are being rendered via a `<slot />`.

• TypeError: app.use is not a function

  cause This error typically indicates that `app` is not a Vue 3 application instance, or you are attempting to use Vue 3's `use` method in a Vue 2 project.
  fix Verify that you are importing `createApp` from 'vue' and using it to initialize your application, and that your project dependencies correctly specify Vue 3.

Warnings

• breaking This package is exclusively built for Vue 3. It is not backward compatible with Vue 2 applications and will lead to errors if used in a Vue 2 project.
  Fix: Ensure your project uses Vue 3 (minimum `vue` peer dependency is `^3.0.5`).
• gotcha When dynamically rendering child items through a `<slot />`, the `:resolve-slot="true"` prop is required on the `<masonry>` component for the layout to correctly detect and arrange these items.
  Fix: Add `:resolve-slot="true"` to your `<masonry>` component when child content is provided via a slot.
• gotcha The component's configuration props (e.g., `cols`, `gutter`) and their behavior are largely inherited from `vue-masonry-css`. Developers should consult the documentation for the original `vue-masonry-css` project for detailed prop usage and examples.
  Fix: Refer to the `vue-masonry-css` GitHub repository (https://github.com/paulcollett/vue-masonry-css) for comprehensive prop documentation.

Install

• npm install vue-next-masonry npm
• yarn add vue-next-masonry yarn
• pnpm add vue-next-masonry pnpm

Imports

• masonry
  wrong:

  const masonry = require('vue-next-masonry');

  correct:

  import masonry from 'vue-next-masonry';

  This package is designed for ESM environments. The default export is used for global component registration via `app.use()`.

Quickstart

Demonstrates global registration of the masonry component and its basic usage in a Vue 3 template with dynamic item heights.

import { createApp } from 'vue';
import masonry from 'vue-next-masonry';

// Assume your root component is App.vue
import App from './App.vue';

const app = createApp(App);

app.use(masonry);

app.mount('#app');

// In your App.vue or any other component's template:
// <template>
//   <masonry :cols="{ default: 3, 700: 2, 500: 1 }" :gutter="20">
//     <div v-for="(item, index) in 10" :key="index" class="masonry-item" :style="{ height: `${50 + Math.random() * 150}px` }">
//       Item {{ item }}
//     </div>
//   </masonry>
// </template>
//
// <style>
// .masonry-item {
//   background-color: #f0f0f0;
//   border: 1px solid #ccc;
//   padding: 10px;
//   margin-bottom: 20px; /* Gutter is handled by the component, this is just for visual clarity */
//   display: flex;
//   align-items: center;
//   justify-content: center;
// }
// </style>