Guide · Open source

How to use Muuri: install, build a grid and add drag and drop

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Muuri is an open-source JavaScript layout engine for building responsive grids of items, such as cards or photos. It also includes animation, filtering, sorting and drag and drop, so you do not need several separate libraries. This guide walks through installing it, adding the markup and styles it requires, and creating your first grid.

Muurihaltu/muuri · ★ 10.9k · MIT Install options & downloads

Quick start

1Install Muuri. Run npm install muuri in your project folder.
2Add a grid element. Create a container div with the class grid and place item divs inside it.
3Add the inner content wrapper. Put a child element with the class item-content inside each item so Muuri can animate visibility.
4Style the elements. Set the grid to position relative and each item to position absolute, and use margin for gaps.
5Initialize the grid. Call new Muuri with the grid selector in your JavaScript.
6Read the API reference. Open the options and methods sections of the README to add filtering, sorting or drag and drop.

Install Muuri with npm

Muuri is installed through the npm package manager. The project's README lists no other prerequisites.

You can also download the files from the project or link them directly from a CDN in a script tag. The README provides both options.

npm install muuri

Add the Web Animations polyfill if needed

Muuri uses the Web Animations API for its animations by default. If you need to support a browser that does not support Web Animations, the README says to add a polyfill, which can be installed with npm.

npm install web-animations-js

Add the grid and item markup

Every grid needs a container element, called the grid element. Each grid item must contain at least two elements. The outer element is used for positioning, and the inner element (the first direct child) is used for show and hide animations.

The class names in the example are not required by Muuri. You can put any markup inside the inner item element.

Grid element: the container for all items.
Item element: the outer element that Muuri positions.
Item content element: the first direct child of the item, used for visibility animations.

<div class="grid">
  <div class="item">
    <div class="item-content">
      This can be anything.
    </div>
  </div>
</div>

Style the grid and items

The grid element must be positioned with a CSS position of relative, absolute or fixed. Item elements must have position set to absolute. Items must not have CSS transitions or animations, because they may conflict with Muuri's animation engine. Gaps between items are controlled with margin on the item elements.

Do not set overflow to auto or scroll on the grid element. The README warns that Muuri's calculations do not account for this, and item jumps will appear when dragging starts. Put a wrapper element around the grid and set the overflow there instead.

Grid element: position relative, absolute or fixed.
Item elements: position absolute.
Gaps: use margin on items.
Never set overflow auto or scroll on the grid element.

.grid {
  position: relative;
}
.item {
  display: block;
  position: absolute;
  width: 100px;
  height: 100px;
  margin: 5px;
  z-index: 1;
  background: #000;
  color: #fff;
}
.item.muuri-item-dragging {
  z-index: 3;
}
.item.muuri-item-releasing {
  z-index: 2;
}
.item.muuri-item-hidden {
  z-index: 0;
}
.item-content {
  position: relative;
  width: 100%;
  height: 100%;
}

Create the grid in JavaScript

The minimum setup needs only the grid element, or a selector that Muuri uses to find it. Every other option is optional. The README notes that Muuri's default options are stored in Muuri.defaultOptions, and they include settings for layout, sorting and drag and drop.

Muuri is a constructor, so it must be called with the new keyword. Options such as dragEnabled and sortData are passed as an object in the second argument.

The grid element can be passed directly or as a selector string.
Options are optional; the defaults include dragEnabled set to false.
Use new Muuri, since it is a constructor function.

var grid = new Muuri('.grid');

Use the API for layout, filtering, sorting and drag and drop

The README's API section documents the Grid constructor, grid options, grid methods, grid events and item methods. Use the options reference to turn on features such as drag and drop, and check the methods and events sections for the calls that update the layout after changes.

The README lists drag and drop between grids, auto-scrolling during drag, nested grids, filtering and sorting among its features. Check the API reference for the exact method names before you use them.

Drag and drop can work between grids.
Filtering and sorting are built into the core.
Layout calculations can run asynchronously in web workers.

What people use it for

Card grids on a website that should rearrange when the screen size changes.
Photo galleries where visitors can drag images into a different order.
Dashboards with filterable tiles of mixed sizes.
Custom layouts that go beyond what CSS grid or flexbox can do alone.

Frequently asked questions

Is Muuri free to use?

Yes. The project is licensed under the MIT License, as listed in its repository. Check the license file in the repository for the full terms.

How do I install Muuri?

Install it with npm using npm install muuri. The README also describes downloading the files or linking a CDN script tag.

Does Muuri need any prerequisites?

The project lists no prerequisites. Setup does require writing JavaScript and CSS rules, so some coding experience is needed.

Do I need a polyfill for Muuri?

Only if you must support browsers without the Web Animations API. The README says Muuri uses Web Animations by default and recommends the web-animations-js polyfill for other browsers.

Why does my grid jump when I start dragging?

The README warns against setting overflow to auto or scroll on the grid element, because Muuri's calculations do not account for it. Move the scrolling to a wrapper element instead.

Is Muuri better than CSS grid or Masonry?

The README says CSS is often enough for simple layouts and that Muuri adds complexity, so use CSS for simple cases. It describes Muuri as a combination of Packery, Masonry, Isotope and Sortable, so it suits projects that need layout, animation and interaction in one library.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Muuri suits front-end developers who need custom grids with drag and drop, filtering or sorting in one library. If a simple layout works with CSS grid or flexbox, the project's own README suggests using those instead, and people without JavaScript experience may find setup difficult.

Install options & downloads