Options
- Recommended
- itemSelector
- columnWidth
- Layout
- Element sizing
- gutter
- percentPosition
- stamp
- isFitWidth
- isOriginLeft
- isOriginTop
- Setup
- containerStyle
- transitionDuration
- isResizeBound
- isInitLayout
All options are optional, but columnWidth
and itemSelector
are recommended.
// jQuery
$('.grid').masonry({
columnWidth: 200,
itemSelector: '.grid-item'
});
// vanilla JS
var msnry = new Masonry( '.grid', {
columnWidth: 200,
itemSelector: '.grid-item'
});
<!-- in HTML -->
<div class="grid js-masonry"
data-masonry-options='{ "columnWidth": 200, "itemSelector": ".grid-item" }'>
Recommended
itemSelector
Specifies which child elements will be used as item elements in the layout.
We recommend always setting itemSelector
. itemSelector
is useful to exclude sizing elements or other elements that are not part of the layout.
itemSelector: '.grid-item'
<div class="grid">
<!-- do not use banner in Masonry layout -->
<div class="static-banner">Static banner</div>
<div class="grid-item"></div>
<div class="grid-item"></div>
...
</div>
columnWidth
Aligns items to a horizontal grid.
We recommend setting columnWidth
. If columnWidth
is not set, Masonry will use the outer width of the first item.
columnWidth: 80
Use element sizing for responsive layouts with percentage widths. Set columnWidth
to an Element or Selector String to use the outer width of the element for the size of the gutter.
<div class="grid">
<!-- .grid-sizer empty element, only used for element sizing -->
<div class="grid-sizer"></div>
<div class="grid-item"></div>
<div class="grid-item grid-item--width2"></div>
...
</div>
/* fluid 5 columns */
.grid-sizer,
.grid-item { width: 20%; }
/* 2 columns wide */
.grid-item--width2 { width: 40%; }
// use outer width of grid-sizer for columnWidth
columnWidth: '.grid-sizer',
itemSelector: '.grid-item',
percentPosition: true
Layout
Element sizing
Sizing options columnWidth
and gutter
can be set with an element. The size of the element is then used as the value of the option.
<div class="grid">
<!-- .grid-sizer empty element, only used for element sizing -->
<div class="grid-sizer"></div>
<div class="grid-item"></div>
<div class="grid-item grid-item--width2"></div>
...
</div>
/* fluid 5 columns */
.grid-sizer,
.grid-item { width: 20%; }
/* 2 columns wide */
.grid-item--width2 { width: 40%; }
// use outer width of grid-sizer for columnWidth
columnWidth: '.grid-sizer',
// do not use .grid-sizer in layout
itemSelector: '.grid-item',
percentPosition: true
The option can be set to a Selector String or an Element.
// set to a selector string
// first matching element within container element will be used
columnWidth: '.grid-sizer'
// set to an element
columnWidth: $grid.find('.grid-sizer')[0]
Element sizing options allow you to control the sizing of the Masonry layout within your CSS. This is useful for responsive layouts and media queries.
/* 3 columns by default */
.grid-sizer { width: 33.333%; }
@media screen and (min-width: 768px) {
/* 5 columns for larger screens */
.grid-sizer { width: 20%; }
}
gutter
Adds horizontal space between item elements.
"gutter": 10
To set vertical space between elements, use margin
CSS.
"gutter": 10
.grid-item {
margin-bottom: 10px;
}
Use element sizing for responsive layouts with percentage widths. Set gutter
to an Element or Selector String to use the outer width of the element.
<div class="grid">
<div class="grid-sizer"></div>
<div class="gutter-sizer"></div>
<div class="grid-item"></div>
<div class="grid-item grid-item--width2"></div>
...
</div>
.grid-sizer,
.grid-item { width: 22%; }
.gutter-sizer { width: 4%; }
.grid-item--width2 { width: 48%; }
columnWidth: '.grid-sizer',
gutter: '.gutter-sizer',
itemSelector: '.grid-item',
percentPosition: true
percentPosition
Sets item positions in percent values, rather than pixel values. percentPosition: true
works well with percent-width items, as items will not transition their position on resize.
// set positions with percent values
percentPosition: true,
columnWidth: '.grid-sizer',
itemSelector: '.grid-item'
/* fluid 5 columns */
.grid-sizer,
.grid-item { width: 20%; }
stamp
Specifies which elements are stamped within the layout. Masonry will layout items 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 class="grid">
<div class="stamp stamp1"></div>
<div class="stamp stamp2"></div>
<div class="grid-item"></div>
<div class="grid-item"></div>
....
</div>
// specify itemSelector so stamps do get laid out
itemSelector: '.grid-item',
// stamp elements
stamp: '.stamp'
/* position stamp elements with CSS */
.stamp {
position: absolute;
background: orange;
border: 4px dotted black;
}
.stamp1 {
left: 30%;
top: 10px;
width: 20%;
height: 100px;
}
.stamp2 {
right: 10%;
top: 20px;
width: 70%;
height: 30px;
}
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
does not work with element sizing with percentage width. Either columnWidth
needs to be set to a fixed size, like columnWidth: 120
, or items need to have a fixed size in pixels, like width: 120px
. Otherwise, the container and item widths will collapse on one another.
isFitWidth: true
/* center container with CSS */
.grid {
margin: 0 auto;
}
isOriginLeft
Controls the horizontal flow of the layout. By default, item elements start positioning at the left, with isOriginLeft: true
. Set isOriginLeft: 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, with isOriginTop: true
. Set isOriginTop: false
for bottom-up layouts. It’s like Tetris!
isOriginTop: false
Setup
containerStyle
CSS styles that are applied to the container element.
// default
// containerStyle: { position: 'relative' }
// disable any styles being set on container
// useful if using absolute position on container
containerStyle: null
transitionDuration
Duration of the transition when items change position or appearance, set in a CSS time format. Default: transitionDuration: '0.4s'
// fast transitions
transitionDuration: '0.2s'
// slow transitions
transitionDuration: '0.8s'
// no transitions
transitionDuration: 0
isResizeBound
Adjusts sizes and positions when window is resized. Enabled by default isResizeBound: true
.
// disable resize logic
isResizeBound: false
/* grid has fixed width */
.grid {
width: 320px;
}
isInitLayout
Enables layout on initialization.
Enabled by default isInitLayout: true
.
Set isInitLayout: false
to disable layout on initialization, so you can use methods or add events before the initial layout.
var $grid = $('.grid').masonry({
// disable initial layout
isInitLayout: false,
//...
});
// bind event
$grid.masonry( 'on', 'layoutComplete', function() {
console.log('layout is complete');
});
// manually trigger initial layout
$grid.masonry();