Masonry

1. Options
2. Methods
3. Events
4. Appendix
5. FAQ

Options

• containerStyle
• columnWidth
• gutter
• hiddenStyle
• isFitWidth
• isInitLayout
• isOriginLeft
• isOriginTop
• isResizeBound
• itemSelector
• stamp
• transitionDuration
• visibleStyle
• Element sizing

All options are optional, but columnWidth and itemSelector are recommended.

var container = document.querySelector('#container');
var msnry = new Masonry( container, {
  columnWidth: 200,
  itemSelector: '.item'
});

// with jQuery
$('#container').masonry({
  columnWidth: 200,
  itemSelector: '.item'
});

<!-- in HTML -->
<div id="container" class="js-masonry"
  data-masonry-options='{ "columnWidth": 200, "itemSelector": ".item" }'>

containerStyle

CSS styles that are applied to the container element. To disable Masonry from setting any CSS to the container element, set containerStyle: null.

columnWidth

The width of a column of a horizontal grid.

If columnWidth is not set, Masonry will use the outer width of the first element.

"columnWidth": 60

If set to an Element or Selector String, Masonry will use the width of that element. See Element sizing. Setting columnWidth with element sizing is recommended if you are using percentage widths.

<div id="column-width-demo2">
  <div class="grid-sizer"></div>
  <div class="item"></div>
  <div class="item"></div>
  ...
</div>

#column-width-demo2 .grid-sizer { width: 20%; }
#column-width-demo2 .item { width: 20%; }
#column-width-demo2 .item.w2 { width: 40%; }

"columnWidth": ".grid-sizer",
"itemSelector": ".item"

gutter

The horizontal space between item elements.

"gutter": 10

To set vertical space between elements, use margin CSS.

"gutter": 10

#gutter-opt-demo2 .item {
  margin-bottom: 10px;
}

If set to an Element or Selector String, Masonry will use the width of that element. See Element sizing.

<div id="gutter-opt-demo3">
  <div class="gutter-sizer"></div>
  <div class="item"></div>
  <div class="item"></div>
  ...
</div>

#gutter-opt-demo3 .gutter-sizer { width: 3%; }

"gutter": ".gutter-sizer",
"itemSelector": ".item"

hiddenStyle

The style applied to hide items.

isFitWidth

Sets the width of the container to fit the available number of columns, based the size of container's parent element. When enabled, you can center the container with CSS.

"isFitWidth": true

/* center container with CSS */
#fit-width .masonry {
  margin: 0 auto;
}

isInitLayout

Enables layout on initialization. Set this to false to disable layout on initialization, so you can use methods or add events before the initial layout.

var msnry = new Masonry( container, {
  // disables initial layout
  isInitLayout: false
});
msnry.on( 'layoutComplete', function() {
  console.log('layout is complete');
});
// manually trigger initial layout
msnry.layout();

isOriginLeft

Controls the horizontal flow of the layout. By default, item elements start positioning at the left. Set to false for right-to-left layouts.

"isOriginLeft": false

isOriginTop

Controls the vertical flow of the layout. By default, item elements start positioning at the top. Set to false for bottom-up layouts. It’s like Tetris!

"isOriginTop": false

isResizeBound

Binds layout to window resizing.

isResizeBound binds layout only when the Masonry instance is first initialized. You can bind and unbind resize layout afterwards with the bindResize and unbindResize methods.

itemSelector

Specifies which child elements to be used as item elements. Setting itemSelector is always recommended. itemSelector is useful to exclude sizing elements.

"itemSelector": ".item"

stamp

Specifies which elements are stamped within the layout. These are special layout elements which will not be laid out by Masonry. Rather, Masonry will layout item elements below stamped elements.

The stamp option stamps elements only when the Masonry instance is first initialized. You can stamp additional elements afterwards with the stamp method.

<div id="stamp-opt-demo">
  <div class="stamp stamp1"></div>
  <div class="stamp stamp2"></div>
  <div class="item"></div>
  <div class="item"></div>
  ....
</div>

"itemSelector": ".item",
"stamp": ".stamp"

/* position stamp elements with CSS */
#stamp-opt-demo {
  position: relative;
}
#stamp-opt-demo .stamp {
  position: absolute;
  background: orange;
  border: 4px dotted black;
}
#stamp-opt-demo .stamp1 {
  left: 30%;
  top: 10px;
  width: 20%;
  height: 100px;
}
#stamp-opt-demo .stamp2 {
  right: 10%;
  top: 20px;
  width: 70%;
  height: 30px;
}

transitionDuration

Duration of the transition when items change position or appearance, set in a CSS time format.

To disable all transitions, set transitionDuration: 0.

visibleStyle

The style applied to reveal hidden items.

Element sizing

For the sizing options columnWidth and gutter, you may set these options to an Element or String, in addition to a Number.

With an Element, Masonry will use its outer width to set the value of the related property.

<div id="container">
  <div class="grid-sizer"></div>
  <div class="item"></div>
  <div class="item"></div>
  ...
</div>

var container = document.querySelector('#container');
var msnry = new Masonry( container, {
  itemSelector: '.item',
  columnWidth: container.querySelector('.grid-sizer')
});

With a String, Masonry will use the string as a selector to get the first matching element within the container element. The size of that element is then used.

"columnWidth": ".grid-sizer"

This allows you to control the size of the Masonry layout just with your CSS. This is useful for responsive layouts, keeping control within CSS so you can rely on media queries.

/* 5 columns by default */
.grid-sizer { width: 20%; }

@media screen and (min-width: 720px) {
  /* 10 columns for larger screens */
  .grid-sizer { width: 10%; }
}

If you are using element sizing, be sure to set itemSelector as well, so the sizing element does not get used in the layout.