Usage

The HTML Structure

The only real important thing here is the data-groups attribute. It has to be a valid JSON array of strings. Optionally, it can be a string delimeted by a value you provide. See delimeter in the options.

This example is using this site's grid. Each item would be 4 columns at the "sm" breakpoint (768px).

Images

To see why the images are wrapped in .aspect elements, check out the images demo.

<div id="grid" class="row my-shuffle-container">
  <figure class="col-4@sm picture-item" data-groups='["photography"]' data-date-created="2010-09-14" data-title="Baseball">
    <div class="aspect aspect--16x9">
      <div class="aspect__inner">
        <img src="/img/baseball.png" alt="" height="145" width="230">
      </div>
    </div>
    <figcaption>Baseball</figcaption>
  </figure>
  <figure class="col-4@sm picture-item" data-groups='["wallpaper","3d"]' data-date-created="2011-08-14" data-title="Tennis">
    <div class="aspect aspect--16x9">
      <div class="aspect__inner">
        <img src="/img/tennis-ball.png" alt="" height="145" width="230">
      </div>
    </div>
    <figcaption>Tennis</figcaption>
  </figure>
  <figure class="col-4@sm picture-item" data-groups='["wallpaper","3d"]' data-date-created="2009-05-27" data-title="iMac">
    <div class="aspect aspect--16x9">
      <div class="aspect__inner">
        <img src="/img/imac.png" alt="" height="145" width="230">
      </div>
    </div>
    <figcaption>iMac</figcaption>
  </figure>
  <div class="col-1@sm my-sizer-element"></div>
</div>

How column widths work

There are 4 options for defining the width of the columns:

  1. Use a sizer element. This is the easiest way to specify column and gutter widths. Add the sizer element and make it 1 column wide. Shuffle will measure the width and margin-left of this sizer element each time the grid resizes. This is awesome for responsive or fluid grids where the width of a column is a percentage.
  2. Use a function. When a function is used, its first parameter will be the width of the shuffle element. You need to return the column width for shuffle to use (in pixels).
  3. A number. This will explicitly set the column width to your number (in pixels).
  4. By default, shuffle will use the width of the first item to calculate the column width.

A basic setup example

If you want functional buttons, check out the js file.

Shuffle uses a UMD definition so that you can use it with globals, AMD, or CommonJS.

var Shuffle = window.shuffle;
var element = document.getElementById('grid');
var sizer = element.querySelector('.my-sizer-element');

var shuffle = new Shuffle(element, {
  itemSelector: '.picture-item',
  sizer: sizer // could also be a selector: '.my-sizer-element'
});