Vue3 Masonry CSS

A lightweight and customizable Masonry Grid component for Vue, powered by native CSS columns. Perfect for building responsive, gap-free layouts — with zero dependencies and full control over structure, styling, and breakpoints.

📚 Table of Contents

• ✨ Features
• ❓ Why Vue3 Masonry CSS?
• 📦 Installation
• 🚀 Basic Usage
• ⚙️ Props

✨ Features

• 🧱 Simple Masonry Layout using CSS columns
• 🎯 Responsive column & gutter configuration with breakpoints
• 💅 Built-in styling (or fully customizable)
• 🧩 Flexible tag and class configuration for all levels
• 💨 Lightweight and dependency-free
• ⚙️ Fully compatible with Vue 3 Composition API + TypeScript

❓ Why Vue3 Masonry CSS?

Unlike JavaScript-heavy masonry libraries, vue3-masonry-css uses native CSS columns, offering a lightweight, dependency-free layout solution that's:

• 🧱 Fully responsive — adapts to any screen size with breakpoint support
• 🎨 Easy to customize — tag names, classes, and attributes are fully configurable
• ⚡ Fast to render — no layout shift, thanks to pure CSS-based rendering
• 🪶 Lightweight — no dependencies, no runtime overhead
• 🛠️ Dev-friendly — built with TypeScript and Vue 3 Composition API
• 🧩 Flexible — works with any child components or elements you provide

📦 Installation

Install using yarn

yarn add vue3-masonry-css

Install using NPM

npm install --save vue3-masonry-css

🚀 Basic Usage

<template>
  <MasonryGrid 
    :columns="{ default: 4, 1024: 3, 768: 2, 480: 1 }"
    :gutter="'1rem'"
  >
    <MasonryGridItem>
      <Component1 />
    </MasonryGridItem>
    <MasonryGridItem>
      <Component2 />
    </MasonryGridItem>
    <MasonryGridItem>
      <Component3 />
    </MasonryGridItem>
  </MasonryGrid>
</template>

<script setup lang="ts">
import { MasonryGrid, MasonryGridItem } from 'vue3-masonry-css';
</script>

⚙️ Props

| Prop | Type | Default | Description | | ----------------------------- | ------------------------------------------------------ | ----------- | --------------------------------------------------------------------- | | columns | number \| Record<number, number> | 2 | Static or responsive column count. | | gutter | number \| string \| Record<number, number \| string> | 0 | Define static gutter width or dynamic gutter width using breakpoints. | | css | boolean | true | Set to false if you want to use custom styling. | | tag | string | 'div' | The HTML tag name of the container element. | | class | any | undefined | Custom class of the container element. | | columnTag | string | 'div' | The HTML tag name of the column element. | | columnClass | any | undefined | Custom class of the column element. | | columnAttr | any | undefined | Custom attributes of the column element. | | childTag | string | 'div' | The HTML tag name of the child element. | | childClass | any | undefined | Custom class of the child element. | | childAttr | any | undefined | Custom attributes of the child element. |

columns

Define static column count or dynamic column count using breakpoints.

Static column count

<masonry :cols="3">...</masonry>

Dynamic column count

<masonry :cols="{ default: 4, 1920: 3, 1366: 2, 1280: 1 }">...</masonry>

gutter

Define static gutter width or dynamic gutter width using breakpoints.

The value can be a number (e.g. 10 for 10px) or a string value (e.g. 10px or 2rem).

Static gutter width

<masonry :gutter="10">...</masonry>
<masonry :gutter="'2rem'">...</masonry>

Dynamic gutter width

<masonry :gutter="{ default: 50, 1920: '30px', 1366: '2rem' }">...</masonry>

css

Set to false if you want to use custom styling.

Default: true

tag

The HTML tag name of the container element.

Default: 'div'

class

Custom class of the container element.

Default: undefined

columnTag

The HTML tag name of the column element.

Default: 'div'

columnClass

Custom class of the column element.

Default: undefined

columnAttr

Custom attributes of the column element.

Default: undefined

childTag

The HTML tag name of the child element.

Default: 'div'

childClass

Custom class of the child element.

Default: undefined

childAttr

Custom attributes of the child element.

Default: undefined

🤝 Contributing

Contributions, issues, and feature requests are welcome!
Feel free to check issues and open a pull request.

1. Fork the repo
2. Create your feature branch (git checkout -b feat/something)
3. Commit your changes
4. Push to the branch
5. Open a PR

📝 License

Released under the MIT License
© Tobias Wälde