Gridzy

The easiest way to configure Gridzy is, to add the option parameters as HTML attributes, always prefixed by data-gridzy- …

<div class="gridzy" data-gridzy-spaceBetween="20" data-gridzy-desiredHeight="400">
      <img src="https://placeimg.com/640/480/any?1" alt="a random image" />
      <img src="https://placeimg.com/640/480/any?2" alt="another random image" />
      <img src="https://placeimg.com/640/480/any?3" alt="yet another random image" />
      <img src="https://placeimg.com/640/480/any?4" alt="a random image again" />
      <img src="https://placeimg.com/640/480/any?5" alt="one last random image" />
    </div>

Main Options

A few more advanced options you can find at Gridzy.js 2 – API.

Layout Options

Gridzy.js 2 supports two different layouts (see layout in the main options above). Each layout has its own additional option parameters:

justified

waterfall

However, you can customize Gridzy.js 2 much more to your needs. Take a look at Gridzy.js 2 – Semantic HTML.

The basic usage of Gridzy.js 2 is incredible simple, but you may want to use an other HTML structure. Gridzy.js 2 is very flexible in this respect. There are only a few points to consider …

The simplest HTML structure of Gridzy is this:

<div class="gridzy">
      <img src="https://placeimg.com/640/480/any?1" alt="a random image" />
      <img src="https://placeimg.com/640/480/any?2" alt="another random image" />
      <img src="https://placeimg.com/640/480/any?3" alt="yet another random image" />
      <img src="https://placeimg.com/640/480/any?4" alt="a random image again" />
      <img src="https://placeimg.com/640/480/any?5" alt="one last random image" />
    </div>

But the following example would work as well:

<ul class="gridzy">
      <li>
        <span>
          <img class="gridzyImage" src="https://placeimg.com/640/480/any?1" alt="a random image" />
        </span>
      </li>
      <li>
        <span>
          <img class="gridzyImage" src="https://placeimg.com/640/480/any?2" alt="another random image" />
        </span>
      </li>
      <li>
        <span>
          <img class="gridzyImage" src="https://placeimg.com/640/480/any?3" alt="yet another random image" />
        </span>
      </li>
      <li>
        <span>
          <img class="gridzyImage" src="https://placeimg.com/640/480/any?4" alt="a random image again" />
        </span>
      </li>
      <li>
        <span>
          <img class="gridzyImage" src="https://placeimg.com/640/480/any?5" alt="one last random image" />
        </span>
      </li>
    </ul>

This may not be a very useful structure, but it shows what’s possible. Just always consider these points:

• The container element can be any tag type, such as ul, but always needs the class gridzy.
• Each direct child element always represents one item in the grid and can be any tag type as well, such as li.
• If you use tag types with browser default styles (such as ul and li), you need to reset the browser defaults yourself.
• If the img element isn’t such a direct child itself, it needs the class gridzyImage, whereby it can be anywhere in the structure.
  

Captions

Especially if you like to add captions, you need an advanced HTML structure. Regardless of styling, this might be a good solution:

<div class="gridzy">
      <figure>
        <img class="gridzyImage" src="https://placeimg.com/640/480/any?1" alt="a random image" />
        <figcaption>a caption text</figcaption>
      </figure>
      <figure>
        <img class="gridzyImage" src="https://placeimg.com/640/480/any?2" alt="another random image" />
        <figcaption>another caption text</figcaption>
      </figure>
      <figure>
        <img class="gridzyImage" src="https://placeimg.com/640/480/any?3" alt="yet another random image" />
        <figcaption>yet another caption text</figcaption>
      </figure>
      <figure>
        <img class="gridzyImage" src="https://placeimg.com/640/480/any?4" alt="a random image again" />
        <figcaption>a caption text again</figcaption>
      </figure>
      <figure>
        <img class="gridzyImage" src="https://placeimg.com/640/480/any?5" alt="one last random image" />
        <figcaption>one last caption text</figcaption>
      </figure>
    </div>

For caption appearance, see Gridzy.js 2 – Captions & Skins.

If you want to add captions to your gallery, you need to define the appearance. Therefore, some predefined skins are available …

Each skin consisting of a CSS file. You need to add this file in addition to the main Gridzy files (usually in the head section):

<link rel="stylesheet" href="gridzy/skins/gridzySkinClassic/style.min.css" />
    

Furthermore you need an advanced HTML structure:

<div class="gridzy gridzySkinClassicLight">
      <figure>
        <img class="gridzyImage" src="https://placeimg.com/640/480/any?1" alt="a random image" />
        <figcaption class="gridzyCaption">a caption text</figcaption>
      </figure>
      <figure>
        <img class="gridzyImage" src="https://placeimg.com/640/480/any?2" alt="another random image" />
        <figcaption class="gridzyCaption">another caption text</figcaption>
      </figure>
      <figure>
        <img class="gridzyImage" src="https://placeimg.com/640/480/any?3" alt="yet another random image" />
        <figcaption class="gridzyCaption">yet another caption text</figcaption>
      </figure>
      <figure>
        <img class="gridzyImage" src="https://placeimg.com/640/480/any?4" alt="a random image again" />
        <figcaption class="gridzyCaption">a caption text again</figcaption>
      </figure>
      <figure>
        <img class="gridzyImage" src="https://placeimg.com/640/480/any?5" alt="one last random image" />
        <figcaption class="gridzyCaption">one last caption text</figcaption>
      </figure>
    </div>

If you are wondering about the HTML structure, I recommend reading Gridzy.js 2 – Semantic HTML.

For the caption you can use any tag type, just ensure it has the class gridzyCaption. The img element needs the class gridzyImage.

As you can see above, the skin name gridzySkinClassic is placed in the path of the CSS file, while in the HTML code you can see gridzySkinClassicLight instead. This is because most predefined skins have a dark and a light version, that are placed in the same file. So, if you would like to use the dark version, just replace gridzySkinClassicLight with gridzySkinClassic.

Included Skins

All the above skins only need a CSS file, but there are additional skins that also require a JavaScript file:

<link rel="stylesheet" href="gridzy/skins/gridzySkinBlur/style.min.css" />
    <script src="gridzy/skins/gridzySkinBlur/script.min.js"></script>

All predefined skins only support simple text captions. Just add your own CSS to use more complex capture structures.

To create your very own skin, please see Gridzy.js 2 – Style Gridzy.

Gridzy.js 2 has a few very simple predefined skins, but you can create your very own one. There is also a possibility, to provide your presumably better skin to the whole Gridzy community …

How To Start

The easiest way is to first copy an existing skin and adapt it to your own needs. The predefined skin gridzySkinBlank would usually provide a good foundation:

/** SKIN Blank **/
    
    /* all gallery items (direct children of the main container element) */
    .gridzySkinBlank > .gridzyItem {
      overflow: hidden;
    }
    
    /* all gallery images (predefined in Gridzy's main CSS file, but can be overridden) */
    .gridzySkinBlank .gridzyImage {
    }
    
    /* all gallery captions (just create your very own style) */
    .gridzySkinBlank .gridzyCaption {
      margin: 0;
      padding: .5em;
      opacity: 0;
      display: flex;
      justify-content: center;
      align-items: center;
      text-align: center;
      position: absolute;
      z-index: 1;
      top: 0;
      left: 0;
      width: 100%;
      height: 100%;
      box-sizing: border-box;
      transition: opacity .5s;
      overflow: auto;
      background: rgba(0, 0, 0, .7);
      color: rgb(255, 255, 255);
    }
    
    .gridzySkinBlank > .gridzyItem:hover .gridzyCaption {
      opacity: 1;
    }
    

In the CSS file you’ll find the classes gridzySkinBlank, gridzyImage and gridzyCaption. Gridzy itself doesn’t need these classes. They are only used for styling and so you can remove or rename them if you like.

Additionally you’ll find the CSS class gridzyItem. Gridzy sets this class automatically to all direct children of the main container element. So, you can use this class to style the items of your gallery.

Mind Important Things

1. The item contents should be fully responsive. Consider that the element size will definitely change. Use percentage values instead of pixel values. And take a look at the Gridzy layout option autoFontSize, which binds the font-size onto the item box size.
2. Each item should have a well-defined aspect ratio. The item’s aspect ratio will never change and is needed to calculate the grid. So if an item doesn’t automatically have a well-defined aspect ratio, predefine it manually (e.g. via css).

In some cases, it may be easier to style the content of the items before Gridzy is initializing. Simply remove the class gridzy or the Gridzy javascript file temporarily for this.

That’s it! That’s all you need to build your very own skin. Most of the predefined skins doesn’t use more that this.

But there could be more if you like …

Advanced Skins

Gridzy uses more CSS classes than only gridzyItem. Most of them will be set automatically and you can use them for styling too.

Main Container Classes

Item Classes

By default the progress indicator and the animations for appearing and disappearing images are predefined by the Gridzy main CSS file.

With these above mentioned CSS classes you can style your own progress indicator and animations. Dare a look into the Gridzy main CSS file, to understand what you would have to override. No fear, everything is well documented there.

Share Your Skin – Get Famous

If you would like to share your skin with the Gridzy community, that would be really awesome. I’m sure some of you can make better skins than me. So you could help to make Gridzy even better.

If you provide your skin, I would place your name and your website URL everywhere the skin is mentioned, and in the skin file itself anyway (of course, only if you prefer not to remain anonymous). Just send me your skin or the URL of the website where I can find it and tell me what information you would like to share. ?

If the needed CSS is mixed with other CSS, don’t think about it. I would pick it for you. Just send me the URL, where I can find it.

If you finished your styling and you are happy with it, you may be interested to optimize the loading process to make all perfect. Please check out Gridzy.js 2 – Optimize Loading.

Gridzy.js 2 itself is a relatively lightweight script, but there are some things you can do to improve the loading process …

Prevent Jumping Images

Gridzy absolutely needs the aspect ratio of all images to calculate the grid. These fact results in jumping elements if some images are ready and others are not. The more images there are, the more annoying can be this effect.

To prevent this behavior, just set width and height attributes for all img elements with the natural image dimensions:

<div class="gridzy">
      <img src="https://placeimg.com/640/480/any?1" width="640" height="480" alt="a random image" />
      <img src="https://placeimg.com/640/480/any?2" width="640" height="480" alt="another random image" />
      <img src="https://placeimg.com/640/480/any?3" width="640" height="480" alt="yet another random image" />
      <img src="https://placeimg.com/640/480/any?4" width="640" height="480" alt="a random image again" />
      <img src="https://placeimg.com/640/480/any?5" width="640" height="480" alt="one last random image" />
    </div>

Thereafter Gridzy can calculate the grid immediately without need to know the actually sizes of the images.

Lazy Loading

To load only images which are in the visible viewport, just follow these steps:

1. Insert width and height attributes as described above
2. Replace all src attributes with data-gridzylazysrc as shown below (if you have srcset attributes as well, replace them with data-gridzylazysrcset).

<div class="gridzy">
      <img data-gridzylazysrc="https://placeimg.com/640/480/any?1" width="640" height="480" alt="a random image" />
      <img data-gridzylazysrc="https://placeimg.com/640/480/any?2" width="640" height="480" alt="another random image" />
      <img data-gridzylazysrc="https://placeimg.com/640/480/any?3" width="640" height="480" alt="yet another random image" />
      <img data-gridzylazysrc="https://placeimg.com/640/480/any?4" width="640" height="480" alt="a random image again" />
      <img data-gridzylazysrc="https://placeimg.com/640/480/any?5" width="640" height="480" alt="one last random image" />
    </div>

After these steps the images will load as soon as they are near or inside the viewport.

If you have many images you may also be interested to filter them in a handy way. Gridzy.js 2 supports a very powerful solution for this. Check out Gridzy.js 2 – Filters.

Filters in Gridzy.js 2 are pretty simple but powerful. No matter what kind of filter do you need, it’s very likely that it’s realizable. All you need is, a bit CSS and a few HTML form elements …

Here is a functional example:

<div id="myFilterControls">
      <button value="*">All</button>
      <button value=".animals">Animals</button>
      <button value=".architecture">Architecture</button>
      <button value=".people">People</button>
    </div>
    
    <div class="gridzy" data-gridzy-filterControls="#myFilterControls button">
      <img class="animals" src="https://placeimg.com/640/480/animals?1" alt="a random animal image" />
      <img class="architecture" src="https://placeimg.com/640/480/arch?1" alt="a random architecture image" />
      <img class="people" src="https://placeimg.com/640/480/people?1" alt="a random people image" />
      <img class="animals" src="https://placeimg.com/640/480/animals?2" alt="another random animal image" />
      <img class="architecture" src="https://placeimg.com/640/480/arch?2" alt="another random architecture image" />
      <img class="people" src="https://placeimg.com/640/480/people?2" alt="another random people image" />
      <img class="animals" src="https://placeimg.com/640/480/animals?3" alt="yet another random animal image" />
    </div>

Let’s Build It Step by Step

1. First we need the usual HTML structure of Gridzy and set class names for all gallery items so we can filter them afterwards

<div class="gridzy">
      <img class="animals" src="https://placeimg.com/640/480/animals?1" alt="a random animal image" />
      <img class="architecture" src="https://placeimg.com/640/480/arch?1" alt="a random architecture image" />
      <img class="people" src="https://placeimg.com/640/480/people?1" alt="a random people image" />
      <img class="animals" src="https://placeimg.com/640/480/animals?2" alt="another random animal image" />
      <img class="architecture" src="https://placeimg.com/640/480/arch?2" alt="another random architecture image" />
      <img class="people" src="https://placeimg.com/640/480/people?2" alt="another random people image" />
      <img class="animals" src="https://placeimg.com/640/480/animals?3" alt="yet another random animal image" />
    </div>

In this example we only use one class for each element. But you can also set multiple classes for a single element, if that element should be findable via multiple filters.

2. Then we add some buttons through which we can change the filters then

<button value="*">All</button>
    <button value=".animals">Animals</button>
    <button value=".architecture">Architecture</button>
    <button value=".people">People</button>
    
    <div class="gridzy">
      <img class="animals" src="https://placeimg.com/640/480/animals?1" alt="a random animal image" />
      <img class="architecture" src="https://placeimg.com/640/480/arch?1" alt="a random architecture image" />
      <img class="people" src="https://placeimg.com/640/480/people?1" alt="a random people image" />
      <img class="animals" src="https://placeimg.com/640/480/animals?2" alt="another random animal image" />
      <img class="architecture" src="https://placeimg.com/640/480/arch?2" alt="another random architecture image" />
      <img class="people" src="https://placeimg.com/640/480/people?2" alt="another random people image" />
      <img class="animals" src="https://placeimg.com/640/480/animals?3" alt="yet another random animal image" />
    </div>

Instead of the buttons, you could also use other form elements like checkboxes, radio buttons, select fields and so on.

As you can see, the values of the buttons are usual CSS selectors. As soon as we finished, a click on such a button will display the images that match that CSS selector. Technically it simply sets the filter option to this value.

You can also use much more complex selectors. For example :not(.animals) would work too, as well as .animals.people and .animals, .people.

3. Lastly, we encapsulate the buttons in a div container and bind them to the Gridzy gallery, by setting the filterControls option:

<div id="myFilterControls">
      <button value="*">All</button>
      <button value=".animals">Animals</button>
      <button value=".architecture">Architecture</button>
      <button value=".people">People</button>
    </div>
    
    <div class="gridzy" data-gridzy-filterControls="#myFilterControls button">
      <img class="animals" src="https://placeimg.com/640/480/animals?1" alt="a random animal image" />
      <img class="architecture" src="https://placeimg.com/640/480/arch?1" alt="a random architecture image" />
      <img class="people" src="https://placeimg.com/640/480/people?1" alt="a random people image" />
      <img class="animals" src="https://placeimg.com/640/480/animals?2" alt="another random animal image" />
      <img class="architecture" src="https://placeimg.com/640/480/arch?2" alt="another random architecture image" />
      <img class="people" src="https://placeimg.com/640/480/people?2" alt="another random people image" />
      <img class="animals" src="https://placeimg.com/640/480/animals?3" alt="yet another random animal image" />
    </div>

As you can see, we also use a CSS selector for the filterControls option. The div container with the id attribute only serves to make the buttons easier to select via that CSS selector.

That’s it! Was pretty simple, right?

If you prefer a JavaScript solution, check out the Gridzy.js 2 – API.

Although Gridzy has its own API, most things can be done without it, simply by manipulating the DOM. Gridzy will notice it and adjust the grid. But there is also a very powerful API …

Manipulating the DOM

For all Document Object Model (DOM) manipulations we first need the container element:

// get the container element
    var gridzyElement = document.querySelector('.gridzy');

Add Images

It’s important to fully build and fill the new child element before you add it to the container element. Otherwise Gridzy can’t detect the correct dimensions. 

// create a new img element
    var newImage = document.createElement('img');
    
    // add src attribute (!! before you add it to the container element !!)
    newImage.src = 'https://placeimg.com/640/480/any';
    
    // add it as last element to the container element
    gridzyElement.appendChild(newImage);
    
    // or as first element (or anywhere in between)
    gridzyElement.insertBefore(newImage, gridzyElement.firstChild);
    

Remove Images

// remove the first image
    gridzyElement.removeChild(gridzyElement.firstElementChild);
    

Change Options

// change the spaceBetween option to a specific value
    gridzyElement.setAttribute('data-gridzy-spaceBetween', '10');
    
    // change the layout option to a specific value
    gridzyElement.setAttribute('data-gridzy-layout', 'waterfall');
    
    // reset the spaceBetween option to its default value
    gridzyElement.removeAttribute('data-gridzy-spaceBetween');
    

More about manipulating the DOM you can find at MDN web docs. There is also an Introduction to the DOM available.

Proprietary API

To use the API, we first need the Gridzy instance, which is bind to the Gridzy container element:

// get the Gridzy instance
    var gridzyInstance = document.querySelector('.gridzy').gridzy;
    

Get Option

// get the value of a single option
    var currentLayout = gridzyInstance.getOption('layout');
    

Get All Options

// get all option values as an object
    var currentOptions = gridzyInstance.getOptions();
    

Set Options

// set specific option values
    gridzyInstance.setOptions({
      spaceBetween: 10,
      layout: 'waterfall'
    });
    
    // or reset options to their default values
    gridzyInstance.setOptions({
      spaceBetween: null,
      layout: null
    });
    

Apply Filter

Applying a filter is just setting the option filter that can be any valid CSS selector:

// set the filter to match items with class "animals"
    gridzyInstance.setOptions({
      filter: '.animals'
    });
    
    // reset the filter to match all items again
    gridzyInstance.setOptions({
      filter: '*'
    });
    
    // set the filter to match items without class "animals"
    gridzyInstance.setOptions({
      filter: ':not(.animals)'
    });
    
    // set the filter to match items with class "animals" or "people"
    gridzyInstance.setOptions({
      filter: '.animals, .people'
    });
    
    // set the filter to match items that have both classes, "animals" and "people"
    gridzyInstance.setOptions({
      filter: '.animals.people'
    });

Add Callback Functions

Gridzy.js 2 supports some options for callback functions. They can be set only via the proprietary API, but just like other options:

// same as set other options
    gridzyInstance.setOptions({
      onOptionsChanged: function() {
        // will be executed each time the options have changed.
      },
      onBeforeOptionsChanged: function() {
        // will be executed, before new options take effect.
      }
    });
    

API – Global

There are some functions that are independent of Gridzy instances. So we don’t need to get an instance before.

Get Default Option

// get the default value of a single option
    var defaultLayout = Gridzy.getDefaultOption('layout');
    

Get All Default Options

// get all default option values as an object, including the default layout options of the default layout
    var defaultOptions = Gridzy.getDefaultOptions();
    
    // or get all default option values, including the default layout options of a specific layout
    var defaultOptions = Gridzy.getDefaultOptions('waterfall');
    

Set Default Options

This doesn’t set the options of all already initialized Gridzy instances, but defines the basis for new instances. However, if an option of an existing instance would be reset via the value null, it would uses the new default value.

// set default option values
    Gridzy.setDefaultOptions({
      spaceBetween: 10,
      layout: 'waterfall'
    });
    

You can use this to set options globally, if you call it before DOM is ready. So you wouldn’t need to set options as attributes anymore.

Automatisms

As long as all automatisms of Gridzy.js 2 are active, there is no need for the below methods. But the automatisms can be switched off to use Gridzy in a more traditional way:

// disable automatic initializations
    Gridzy.setDefaultOptions({
      autoInitOnDomReady: false,
      autoInitOnDomMutation: false
    });
    
    // or switch off all mutation observers
    Gridzy.setDefaultOptions({
      autoInitOnDomMutation: false,
      autoSyncChildListMutation: false,
      autoSyncAttributesMutation: false,
      autoSyncChildClassMutation: false
    });
    

Some of these options can’t be set via data-gridzy- attributes or via setOptions(), because of logical reasons:

Initialize Manually

// initialize a new Gridzy instance
    var gridzyInstance = new Gridzy(document.querySelector('.gridzy'), {
      spaceBetween: 10,
      layout: 'waterfall'
    });
    

Destroy the Instance

Roughly said, the opposite of initializing Gridzy.

gridzyInstance.destroy();
    gridzyInstance = null;

Sync Child List Manually

// after child elements (images) are added to or removed from the DOM.
    gridzyInstance.syncChildList();
    

Sync a Single Child Manually

Usually not needed, except in very rare cases.

// after child elements (images) are added to the DOM and only one of them should be synced to Gridzy.
    gridzyInstance.syncChild(childElement);

Sync Attributes Manually

Note that useOptionAttributes option must be true for this.

// after data-gridzy- attributes have changed
    gridzyInstance.syncAttributes();
    

Force Rendering

Usually not needed, even if all automatisms are turned off

gridzyInstance.render();

You reached the end of the documentation! ?

Gridzy.js 2 is so powerful, I can’t portray in the documentation all the things that are possible. But I’m going to publish tips and tricks from time to time. Stay in touch via Twitter or subscribe to my mailing list, where you would receive 30 more Gridzy.js skins as a welcome gift 🎁. If you tell me your name too, that would pleases me. I’m Helmut ✌
I don’t have time to send junk, so be relaxed 😏