options.hbs

---
title: Options
---

{{! --------------------------------------------------- }}

<p>All options are optional, but <a href="#itemselector"><code>itemSelector</code></a> is recommended.</p>

``` js
// jQuery
$('.grid').packery({
  itemSelector: '.grid-item',
  gutter: 10
});
```

``` js
// vanilla JS
var pckry = new Packery( '.grid', {
  itemSelector: '.grid-item',
  gutter: 10
});
```

``` html
<!-- in HTML -->
<div class="grid" data-packery='{ "itemSelector": ".grid-item", "gutter": 10 }'>
```

{{! --------------------------------------------------- }}

<h2>Recommended</h2>

{{! --------------------------------------------------- }}

<h3>itemSelector</h3>

<p>Specifies which child elements will be used as item elements in the layout.</p>

<p>We recommend always setting <code>itemSelector</code>. <code>itemSelector</code> is useful to exclude <a href="#element-sizing">sizing elements</a> or other elements that are not part of the layout.</p>

<div class="duo example">
  <div class="duo__cell example__code">
    ``` js
    itemSelector: '.grid-item'
    ```

    ``` html
    <div class="grid">
      <!-- do not use banner in Packery layout -->
      <div class="static-banner">Static banner</div>
      <div class="grid-item"></div>
      <div class="grid-item"></div>
      ...
    </div>
    ```
  </div>
  <div class="duo__cell example__demo">
    <div class="grid grid--has-banner"
      data-packery='{ "itemSelector": ".grid-item" }'>
      <div class="static-banner">Static banner</div>
      {{> grid-items }}
    </div>
    {{> edit-demo default="pgVNdO" }}
  </div>
</div>

{{! --------------------------------------------------- }}

<h2>Layout</h2>

{{! --------------------------------------------------- }}

<h3>columnWidth</h3>

<p>Aligns items to a horizontal grid. <code>columnWidth</code> is not required for grid layouts, but may help align items when <a href="draggable.html">dragging</a>.</p>

<div class="duo example">
  <div class="duo__cell example__code">
    ``` js
    columnWidth: 60
    ```
  </div>
  <div class="duo__cell example__demo">
    <div class="grid"  data-packery='{ "columnWidth": 60 }'>
      {{> grid-items}}
    </div>
    {{> edit-demo default="eouHb" }}
  </div>
</div>

<p>Use <a href="../options.html#element-sizing">element sizing</a> for responsive layouts with percentage widths. Set <code>columnWidth</code> to an <i>Element</i> or Selector <i>String</i> to use the outer width of the element for the size of the column.</p>

<div class="duo example">
  <div class="duo__cell example__code">
    ``` html
    <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>
    ```

    ``` css
    /* fluid 5 columns */
    .grid-sizer,
    .grid-item { width: 20%; }
    /* 2 columns wide */
    .grid-item--width2 { width: 40%; }
    ```

    ``` js
    // use outer width of grid-sizer for columnWidth
    columnWidth: '.grid-sizer',
    itemSelector: '.grid-item',
    percentPosition: true
    ```
  </div>
  <div class="duo__cell example__demo">
    <div class="grid grid--fluid-5-col"
      data-packery='{ "itemSelector": ".grid-item", "columnWidth": ".grid-sizer",  "percentPosition": true }'>
      <div class="grid-sizer"></div>
      {{> grid-items }}
    </div>
    {{> edit-demo default="tonpx" }}
  </div>
</div>

{{! --------------------------------------------------- }}

<h3>rowHeight</h3>

<p>Aligns items to a vertical grid. <code>rowHeight</code> is not required for grid layouts, but may help align items when dragging items in a <a href="#horizontal">horizontal</a> layout.</p>

<div class="duo example">
  <div class="duo__cell example__code">
    ``` js
    rowHeight: 60
    ```
  </div>
  <div class="duo__cell example__demo">
    <div class="grid"  data-packery='{ "rowHeight": 60 }'>
      {{> grid-items}}
    </div>
    {{> edit-demo default="KGcqD" }}
  </div>
</div>

<p>Use <a href="../options.html#element-sizing">element sizing</a> for responsive layouts with percentage widths. Set <code>rowHeight</code> to an <i>Element</i> or Selector <i>String</i> to use the outer height of the element for the size of the row.</p>

<div class="duo example">
  <div class="duo__cell example__code">
    ``` html
    <div class="grid">
      <!-- .grid-sizer empty element, only used for element sizing -->
      <div class="grid-sizer"></div>
      <div class="grid-item"></div>
      ...
    </div>
    ```

    ``` css
    /* height of 1 row */
    .grid-sizer,
    .grid-item { height: 60px; }
    /* 2 rows high */
    .grid-item--height2 { height: 120px; }
    ```

    ``` js
    // use outer width of grid-sizer for columnWidth
    itemSelector: '.grid-item',
    rowHeight: '.grid-sizer',
    percentPosition: true
    ```
  </div>
  <div class="duo__cell example__demo">
    <div class="grid"
      data-packery='{ "itemSelector": ".grid-item", "rowHeight": ".grid-sizer" }'>
      <div class="grid-sizer grid-sizer--row-height"></div>
      {{> grid-items }}
    </div>
    {{> edit-demo default="dElba" }}
  </div>
</div>

{{! --------------------------------------------------- }}

<h3>gutter</h3>

<p>Adds horizontal and vertical space between item elements.</p>

<div class="duo example">
  <div class="duo__cell example__code">
    ``` js
    gutter: 10
    ```
  </div>
  <div class="duo__cell example__demo">
    <div class="grid grid--has-gutter" data-packery='{ "gutter": 10 }'>
      {{> grid-items }}
    </div>
    {{> edit-demo default="fIbHB" }}
  </div>
</div>

<p>Use <a href="#element-sizing">element sizing</a> for responsive layouts with percentage widths. Set <code>gutter</code> to an <i>Element</i> or Selector <i>String</i> to use the outer width of the element.</p>

<div class="duo example">
  <div class="duo__cell example__code">
    ``` html
    <div class="grid">
      <div class="gutter-sizer"></div>
      <div class="grid-item"></div>
      <div class="grid-item grid-item--width2"></div>
      ...
    </div>
    ```

    ``` css
    .grid-item { width: 22%; }

    .gutter-sizer { width: 4%; }

    .grid-item--width2 { width: 48%; }
    ```

    ``` js
    columnWidth: '.grid-sizer',
    gutter: '.gutter-sizer',
    itemSelector: '.grid-item',
    percentPosition: true
    ```
  </div>
  <div class="duo__cell example__demo" >
    <div class="grid grid--fluid-gutter"
      data-packery='{ "itemSelector": ".grid-item", "gutter": ".gutter-sizer", "percentPosition": true }'>
      <div class="gutter-sizer"></div>
      {{> grid-items-fewer }}
    </div>
    {{> edit-demo default="buyLF" }}
  </div>
</div>

{{! --------------------------------------------------- }}


<h3>Element sizing</h3>

<p>Sizing options <a href="#columnwidth"><code>columnWidth</code></a>, <a href="#rowheight"><code>rowHeight</code></a>, and <a href="#gutter"><code>gutter</code></a> can be set with an element. The size of the element is then used as the value of the option.</p>

<div class="duo example">
  <div class="duo__cell example__code">
    ``` html
    <div class="grid">
      <!-- .grid-sizer & .gutter-sizer empty elements
        only used for element sizing -->
      <div class="grid-sizer"></div>
      <div class="gutter-sizer"></div>
      <div class="grid-item"></div>
      <div class="grid-item grid-item--width2"></div>
      ...
    </div>
    ```

    ``` css
    /* fluid 4 columns, 4% gutter */
    .grid-sizer,
    .grid-item { width: 22%; }

    .gutter-sizer { width: 4%; }

    /* 2 columns wide */
    .grid-item--width2 { width: 40%; }
    ```

    ``` js
    // use outer width of grid-sizer for columnWidth
    columnWidth: '.grid-sizer',
    gutter: '.gutter-sizer',
    // do not use .grid-sizer in layout
    itemSelector: '.grid-item',
    percentPosition: true
    ```
  </div>
  <div class="duo__cell example__demo">
    <div class="grid grid--fluid-gutter"
      data-packery='{ "itemSelector": ".grid-item", "columnWidth": ".grid-sizer", "gutter": ".gutter-sizer",  "percentPosition": true }'>
      <div class="grid-sizer"></div>
      <div class="gutter-sizer"></div>
      {{> grid-items-fewer }}
    </div>
    {{> edit-demo default="ZQoeMr" }}
  </div>
</div>

<p>Options can be set to a Selector <i>String</i> or an <i>Element</i>.</p>

``` js
// 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]
```

<p>Element sizing options allow you to control the sizing of the Packery layout within your CSS. This is useful for responsive layouts and media queries.</p>

``` css
/* 3 columns by default */
.grid-sizer { width: 33.333%; }

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

{{! --------------------------------------------------- }}

<h3>percentPosition</h3>

<p>Sets item positions in percent values, rather than pixel values. <code>percentPosition: <span class="literal">true</span></code> works well with percent-width items, as items will not transition their position on resize.</p>

<div class="duo example">
  <div class="duo__cell example__code">
    ``` js
    // set positions with percent values
    percentPosition: true
    ```

    ``` css
    /* fluid 5 columns */
    .grid-item { width: 20%; }
    ```
  </div>
  <div class="duo__cell example__demo">
    <div class="grid grid--fluid-5-col"
      data-packery='{ "percentPosition": true }'>
      {{> grid-items-fewer }}
    </div>
    {{> edit-demo default="xZjOXq" }}
  </div>
</div>

{{! ----------------------------------------------------------- }}

<h3>stamp</h3>

<p>Specifies which elements are <em>stamped</em> within the layout. Packery will layout items around stamped elements.</p>

<p>The <code>stamp</code> option stamps elements only when the Packery instance is first initialized. You can stamp additional elements afterwards with the <a href="methods.html#stamp"><code>stamp</code> method</a>.</p>

<div class="duo example">
  <div class="duo__cell example__code">
    ``` html
    <div class="grid">
      <div class="stamp stamp1"></div>
      <div class="stamp stamp2"></div>
      <div class="grid-item"></div>
      <div class="grid-item"></div>
      ....
    </div>
    ```

    ``` js
    // specify itemSelector so stamps do get laid out
    itemSelector: '.grid-item',
    // stamp elements
    stamp: '.stamp'
    ```

    ``` css
    /* 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;
    }
    ```
  </div>
  <div class="duo__cell example__demo">
    <div class="grid grid--has-stamp" data-packery='{ "itemSelector": ".grid-item", "stamp": ".stamp" }'>
      <div class="stamp stamp--static1"></div>
      <div class="stamp stamp--static2"></div>
      {{> grid-items}}
    </div>
    {{> edit-demo default="Hqwib" }}
  </div>
</div>

{{! ----------------------------------------------------------- }}

<h3>horizontal</h3>

<p>Lays out items horizontally instead of vertically.</p>

<p><code>horizontal</code> was previously <code>isHorizontal</code> in Packery v1. <code>isHorizontal</code> will still work in Packery v2.</p>

<div class="duo example">
  <div class="duo__cell example__code">
    ``` js
    horizontal: true
    ```
    
    ``` css
    /* containers need height set when horizontal */
    .grid {
      height: 300px;
    }
    ```
  </div>
  <div class="duo__cell example__demo">
    <div class="grid grid--horizontal grid--counting"
      data-packery='{ "horizontal": true }'>
      {{> grid-items }}
    </div>
    {{> edit-demo default="cbLyJ" }}
  </div>
</div>

{{! ----------------------------------------------------------- }}

<h3>originLeft</h3>

<p>Controls the horizontal flow of the layout. By default, item elements start positioning at the left, with <code><span class="comment">originLeft: true</span></code>. Set <code>originLeft: <span class="literal">false</span></code> for right-to-left layouts.</p>

<p><code>originLeft</code> was previously <code>isOriginLeft</code> in Packery v1. <code>isOriginLeft</code> will still work in Packery v2.</p>

<div class="duo example">
  <div class="duo__cell example__code">
    ``` js
    originLeft: false
    ```
  </div>
  <div class="duo__cell example__demo">
    <div class="grid grid--counting"
      data-packery='{ "originLeft": false }'>
      {{> grid-items }}
    </div>
    {{> edit-demo default="rBmsE" }}
  </div>
</div>

{{! ----------------------------------------------------------- }}

<h3>originTop</h3>

<p>Controls the vertical flow of the layout. By default, item elements start positioning at the top, with <code><span class="comment">originTop: true</span></code>. Set <code>originTop: <span class="literal">false</span></code> for bottom-up layouts. It&rsquo;s like Tetris!</p>

<p><code>originTop</code> was previously <code>isOriginTop</code> in Packery v1. <code>isOriginTop</code> will still work in Packery v2.</p>

<div class="duo example">
  <div class="duo__cell example__code">
    ``` js
    originTop: false
    ```
  </div>
  <div class="duo__cell example__demo">
    <div class="grid grid--counting"
      data-packery='{ "originTop": false }'>
      {{> grid-items }}
    </div>
    {{> edit-demo default="Bukmp" }}
  </div>
</div>

{{! ----------------------------------------------------------- }}

<h2>Setup</h2>

{{! ----------------------------------------------------------- }}

<h3>containerStyle</h3>

<p>CSS styles that are applied to the container element.</p>

``` js
// default
// containerStyle: { position: 'relative' }

// disable any styles being set on container
// useful if using absolute position on container
containerStyle: null
```

{{! ----------------------------------------------------------- }}

<h3>transitionDuration</h3>

<p>Duration of the transition when items change position or appearance, set in a CSS time format. Default: <code><span class="comment">transitionDuration: '0.4s'</span></code></p>

``` js
// fast transitions
transitionDuration: '0.2s'

// slow transitions
transitionDuration: '0.8s'

// no transitions
transitionDuration: 0
```

{{! ----------------------------------------------------------- }}

<h3>stagger</h3>

<p>Staggers item transitions, so items transition incrementally after one another. Set as a CSS time format, <code><span class="string">'0.03s'</span></code>, or as a number in milliseconds, <code><span class="number">30</span></code>.</p>

<div class="duo example">
  <div class="duo__cell example__code">
    ``` js
    stagger: 30
    ```
  </div>
  {{> stagger }}
</div>

{{! ----------------------------------------------------------- }}

<h3>shiftResize</h3>


{{! ----------------------------------------------------------- }}

<h3>resize</h3>

<p>Adjusts sizes and positions when window is resized. Enabled by default <code><span class="comment">resize: true</span></code>.</p>

<p><code>resize</code> was previously <code>isResizeBound</code> in Packery v1. <code>isResizeBound</code> will still work in Packery v2.</p>

<div class="duo example">
  <div class="duo__cell example__code">
    ``` js
    // disable window resize behavior
    resize: false
    ```

    ``` css
    /* grid has fixed width */
    .grid {
      width: 320px;
    }
    ```
  </div>
  <div class="duo__cell example__demo">
    <div class="grid grid--fixed-width"
      data-packery='{ "resize": false }'>
      {{> grid-items-fewer }}
    </div>
    {{> edit-demo default="GodQEN" }}
  </div>
</div>

{{! ----------------------------------------------------------- }}

<h3>initLayout</h3>

<p>Enables layout on initialization.
  Enabled by default <code><span class="comment">initLayout: true</span></code>.</p>

<p>Set <code>initLayout: <span class="literal">false</span></code> to disable layout on initialization, so you can use <a href="methods.html">methods</a> or add <a href="events.html">events</a> before the initial layout.</p>

<p><code>initLayout</code> was previously <code>isInitLayout</code> in Packery v1. <code>isInitLayout</code> will still work in Packery v2.</p>

``` js
var $grid = $('.grid').packery({
  // disable initial layout
  initLayout: false,
  //...
});
// bind event
$grid.packery( 'on', 'layoutComplete', function() {
  console.log('layout is complete');
});
// trigger initial layout
$grid.packery();
```

{{> edit-demo default="mVLXMO" vanillaJS="rxvJGP"}}

{{! ----------------------------------------------------------- }}