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