Getting started

HTML markup

Shuffle operates on a group of items, giving you the ability to filter or sort them.

<div id="photo-gallery">
  <div class="picture-item">…</div>
  <div class="picture-item">…</div>
  <div class="picture-item">…</div>
  <div class="picture-item">…</div>
</div>

The easiest way to use Shuffle is to add a data-groups attribute to each of the items in your grid as a valid JSON array of strings.

<figure class="picture-item" data-groups='["nature","city"]'>
  <img src="central-park.jpg" alt="Aerial view of Central Park" />
  <figcaption>Looking down on central park and the surrounding builds from the Rockefellar Center</figcaption>
</figure>

Alternatively, you can set the delimiter option to a comma (delimiter: ',') and the data-groups attribute will be split on that character.

<figure class="picture-item" data-groups="nature,city">
  <img src="central-park.jpg" alt="Aerial view of Central Park" />
  <figcaption>Looking down on central park and the surrounding builds from the Rockefellar Center</figcaption>
</figure>

If you were using Bootstrap v4 grids, you could use the col-* classes like this.

<div class="row" id="photo-gallery">
  <figure class="col-3 picture-item" data-groups='["animal"]'>
    <div class="aspect">
      <img src="crocodile.jpg" alt="A close, profile view of a crocodile looking directly into the camera" />
    </div>
    <figcaption>Crocodile</figcaption>
  </figure>
  <figure class="col-3 picture-item" data-groups='["city"]'>
    <div class="aspect">
      <img src="crossroads.jpg" alt="A multi-level highway stack interchange in Puxi, Shanghai" />
    </div>
    <figcaption>Crossroads</figcaption>
  </figure>
  <figure class="col-3 picture-item" data-groups='["nature","city"]'>
    <div class="aspect">
      <img
        src="central-park.jpg"
        alt="Looking down on central park and the surrounding builds from the Rockefellar Center"
      />
    </div>
    <figcaption>Central Park</figcaption>
  </figure>
  <div class="col-1 js-shuffle-sizer"></div>
</div>

JavaScript

Once the markup is ready, initialize Shuffle by giving it the container element and an optional options object.

const Shuffle = window.Shuffle; // Assumes you're using the UMD version of Shuffle (for example, from unpkg.com).
const element = document.getElementById('photo-gallery');
const sizer = element.querySelector('.js-shuffle-sizer');

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