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. It can also be a string delimeted by a value you provide with the delimiter option.

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

Images

Images are wrapped in .aspect elements to take up the same amount of space the image will when it loads. For details, check out the images demo.

<div class="row my-shuffle-container">
  <figure class="col-4@sm picture-item" data-groups='["animal"]' data-date-created="2016-08-12" data-title="Crocodile">
    <div class="aspect aspect--16x9">
      <div class="aspect__inner">
        <img src="crocodile.jpg" alt="A close, profile view of a crocodile looking directly into the camera" />
      </div>
    </div>
    <figcaption>Crocodile</figcaption>
  </figure>
  <figure class="col-4@sm picture-item" data-groups='["city"]' data-date-created="2016-06-09" data-title="Crossroads">
    <div class="aspect aspect--16x9">
      <div class="aspect__inner">
        <img src="crossroads.jpg" alt="A multi-level highway stack interchange in Puxi, Shanghai" />
      </div>
    </div>
    <figcaption>Crossroads</figcaption>
  </figure>
  <figure class="col-4@sm picture-item" data-groups='["nature","city"]' data-date-created="2015-10-20" data-title="Central Park">
    <div class="aspect aspect--16x9">
      <div class="aspect__inner">
        <img src="central-park.jpg" alt="Looking down on central park and the surrounding builds from the Rockefellar Center" />
      </div>
    </div>
    <figcaption>Central Park</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.querySelector('.my-shuffle-container');
var sizer = element.querySelector('.my-sizer-element');

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