Version 2.x – Gridzy.Gallery

Basic Usage

Upload the Gridzy files to your server and add them to your website (usually in the head section):

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

Add the HTML code (anywhere in the body section):

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

That’s it! That’s a fully functional example. No extra initialization is required.

Configuration

The easiest way to configure Gridzy is, to just use HTML attributes. You only need to prefix the option names with data-gridzy-. So, to set the spaceBetween option, just add the attribute data-gridzy-spaceBetween.

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

Main Options

	Default Value	Description
`animate`	`true`	Determines whether animations should be used when the grid changes (for example, when resizing the browser window or when setting a filter).
`layout`	`justified`	Defines the used layout. Gridzy.js 2 supports the two different layouts `justified` and `waterfall`. Each of them has its own additional option parameters, which you can find below this table.
`filter`	`*`	Determines which images should be shown. Any CSS-selector can be used as value here. Usually set automatically via `filterControls` (see next option). Check out Filters
`filterControls`		Determines which form elements can be used to filter the images. Any CSS selector, that selects HTML form elements, can be used as value here. Check out Filters
`autoConsiderScrollBars`	`true`	To predict the available width if scroll bars appear or disappear. It’s always recommended to leave it on `true` unless this automatism causes problems.

Justified Layout Options

	Default Value	Description
`autoFontSize`	`false`	Automatically updates the font-size property of each box based on the original box size. By default the font-size property is not set explicitly.
`desiredHeight`	`190`	Defines the desired height of element rows. The actual height will be computed depending on the available width and the elements in the row.
`hideOnMissingImage`	`true`	Hides boxes that contain images that could not be loaded.
`spaceBetween`	`4`	Defines the distance between elements in pixels.
`lastRowAlign` since version 2.3.0	`justified`	Defines the behavior of the last row. Allowed values are `left`, `center`, `right` and `justified`.
`singleRowAlign` since version 2.3.0	`justified`	Defines the behavior if there is only one single row. Allowed values are `left`, `center`, `right` and `justified`.
~~`fillLastRow`~~ ~~since version 2.1.0~~	~~`true`~~	REMOVED since version 2.4.0 (DEPRECATED since version 2.3.0) Arranges the images so that the last row is always completely filled. If you plan to append images dynamically, it could be a good idea to deactivate this. Takes no effect on single rows (see `fillSingleRow`).
`fillSingleRow` since version 2.1.0	~~`true`~~	REMOVED since version 2.4.0 (DEPRECATED since version 2.3.0) If there is only one row, it arranges the images so that the row is always completely filled. If it can happen that you have only one or two images in the gallery, it could be a good idea to deactivate this.

Waterfall Layout Options

	Default Value	Description
`autoFontSize`	`false`	Automatically updates the font-size property of each box based on the original box size. By default the font-size property is not set explicitly.
`desiredWidth`	`250`	Defines the desired width of columns. The actual width will be computed depending on the available width and the number of columns.
`hideOnMissingImage`	`true`	Hides boxes that contain images that could not be loaded.
`horizontalOrder`	`false`	Defines that the elements are placed strictly one element in each column from left to right, then starts again in the most left column independent in which column is more place. By default the elements will be always placed in the column with the smallest height.
`spaceBetween`	`4`	Defines the distance between elements in pixels.

More Advanced Options

For more advanced options, check out the API → go to API

Semantic HTML

The simplest HTML structure of Gridzy is this:

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

However, Gridzy is very flexible and you can use almost any other HTML structure. There are only a few points to consider:

Each child of the container element represents one item in the grid.
Both the container element and its children can be any tag type, such as ul and li (just consider to reset browser defaults).
If an img element isn’t a direct child itself, it needs the class gridzyImage.

So this is also a working HTML structure:

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

Especially if you want to add captions, you need an advanced HTML structure. To learn more about it, take a look at Captions & Skins.

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 gridzySkinClassic">
  <figure>
    <img class="gridzyImage" src="https://loremflickr.com/640/480?random=1" alt="a random image" />
    <figcaption class="gridzyCaption">a caption text</figcaption>
  </figure>
  <figure>
    <img class="gridzyImage" src="https://loremflickr.com/480/640?random=2" alt="another random image" />
    <figcaption class="gridzyCaption">another caption text</figcaption>
  </figure>
  <figure>
    <img class="gridzyImage" src="https://loremflickr.com/640/640?random=3" alt="yet another random image" />
    <figcaption class="gridzyCaption">yet another caption text</figcaption>
  </figure>
  <figure>
    <img class="gridzyImage" src="https://loremflickr.com/640/480?random=4" alt="a random image again" />
    <figcaption class="gridzyCaption">a caption text again</figcaption>
  </figure>
  <figure>
    <img class="gridzyImage" src="https://loremflickr.com/640/480?random=5" alt="one last random image" />
    <figcaption class="gridzyCaption">one last caption text</figcaption>
  </figure>
</div>

If you are wondering about the HTML structure, take a look at Semantic HTML.

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

The above example shows you the skin gridzySkinClassic. To use a different one, just replace the skin name with one of these:

Included Skins

	Available Classes
gridzySkinBlank a good starting point for creating an own skin live preview	`gridzySkinBlank`
gridzySkinClassic live preview	`gridzySkinClassic` `gridzySkinClassicLight` (DEPRECATED since version 2.6.0)
gridzySkinFullOverlay live preview	`gridzySkinFullOverlay` `gridzySkinFullOverlayLight` (DEPRECATED since version 2.6.0)
gridzySkinLift live preview	`gridzySkinLift` `gridzySkinLiftLight` (DEPRECATED since version 2.6.0)
gridzySkinMagnifier zoom functionality not included live preview	`gridzySkinMagnifier` `gridzySkinMagnifierLight` (DEPRECATED since version 2.6.0)

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>

	Available Classes
gridzySkinBlur doesn’t work in IE live preview	`gridzySkinBlur` `gridzySkinBlurLight` (DEPRECATED since version 2.6.0)
gridzySkinCard live preview	`gridzySkinCard` `gridzySkinCardLight` (DEPRECATED since version 2.6.0)

Skin Options

Since version 2.6.0 there are Options to configure the built-in skins. Depending on the specific skin you can set the background color, text color and text shadow. You just have to use CSS custom properties as you can see here:

<div class="gridzy gridzySkinClassic" style="--background: rgba(0, 80, 117, .8); --color: rgb(238, 238, 238); ">
  <figure>
    <img class="gridzyImage" src="https://loremflickr.com/640/480?random=1" alt="a random image" />
    <figcaption class="gridzyCaption">a caption text</figcaption>
  </figure>
  <figure>
    <img class="gridzyImage" src="https://loremflickr.com/480/640?random=2" alt="another random image" />
    <figcaption class="gridzyCaption">another caption text</figcaption>
  </figure>

  ...

</div>

Check out the supported variables and default values for each skin here:

gridzySkinClassic

Variable	Default Value	Information
`--background`	`rgba(0, 0, 0, .7)`	allows any CSS background value
`--color`	`rgb(255, 255, 255)`	allows any CSS color value
`--text-shadow`	`none`	allows any CSS text-shadow value

gridzySkinFullOverlay

Variable	Default Value	Information
`--background`	`rgba(0, 0, 0, .7)`	allows any CSS background value
`--color`	`rgb(255, 255, 255)`	allows any CSS color value
`--text-shadow`	`none`	allows any CSS text-shadow value

gridzySkinLift

Variable	Default Value	Information
`--background`	`rgba(0, 0, 0, .7)`	allows any CSS background value
`--color`	`rgb(255, 255, 255)`	allows any CSS color value
`--text-shadow`	`0 0 10px rgb(0, 0, 0), 0 0 20px rgb(0, 0, 0), 0 0 30px rgb(0, 0, 0)`	allows any CSS text-shadow value

gridzySkinMagnifier

Variable	Default Value	Information
`--background`	`rgba(0, 0, 0, .7)`	allows any CSS background value
`--color`	`rgb(255, 255, 255)`	allows any CSS color value

This skin does not support --text-shadow

gridzySkinBlur

Variable	Default Value	Information
`--background`	`rgba(0, 0, 0, .7)`	allows any CSS background value
`--color`	`rgb(255, 255, 255)`	allows any CSS color value
`--text-shadow`	`0 0 10px rgb(0, 0, 0)`	allows any CSS text-shadow value

gridzySkinCard

Variable	Default Value	Information
`--background`	`rgba(0, 0, 0, 1)`	allows any CSS background value
`--color`	`rgb(255, 255, 255)`	allows any CSS color value
`--text-shadow`	`none`	allows any CSS text-shadow value

All predefined skins only support simple text captions. You can create your very own and more complex skins. Please take a look at Style Gridzy.

Style Gridzy

If no predefined skin fits your needs, you can style your own one.

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 as well as a good documentation in the CSS file:

/** 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

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.
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

Class Name	Description
`gridzy` to set manually	Gridzy automatically finds elements with this class and initializes them.
`gridzyAnimated`	Will be set automatically if option `animate` is `true`. If this class is set manually, the option `animate` will automatically get `true` too (except if it’s explicitly set to `false`).

Item Classes

Class Name	Description
`gridzyItem`	Will be set as soon as the item starts the initializing process. Will never be removed.
`gridzyItemInitializing`	Will be set as soon as the item starts the initializing process. Will be replaced by `gridzyItemReady` as soon as the item is fully initialized. Means not that images are fully loaded (see `gridzyItemLoading`), but item is ready to get visible.
`gridzyItemReady`	Will replace `gridzyItemInitializing` as soon as the item is fully initialized. Will never be removed. Means not that images are fully loaded (see `gridzyItemComplete`), but item is ready to get visible.
`gridzyItemLoading`	Will be set as soon as the item starts the initializing process. Will be replaced by `gridzyItemComplete` as soon as the contained images (usually only one) are fully loaded.
`gridzyItemComplete`	Will replace `gridzyItemLoading` as soon as the contained images (usually only one) are fully loaded. Will never be removed.
`gridzyItemInitialToVisible`	Will be set as soon as the item begins to appear the first time. Will be removed as soon as the item is completely visible.
`gridzyItemVisible`	Will be set as soon as the item is fully visible. Will be removed as soon as the item begins to disappear.
`gridzyItemVisibleToHidden`	Will be set as soon as the item begins to disappear. Will be removed as soon as the item is completely hidden.
`gridzyItemHidden`	Will be set as soon as the item is completely hidden. Will be removed as soon as the item begins to appear.
`gridzyItemHiddenToVisible`	Will be set as soon as the item begins to appear (except appearing the first time – see class `gridzyItemInitialToVisible`). Will be removed as soon as the item is completely visible.
`gridzyItemVisibleToVisible`	Will be set as soon as something in the grid changed, but the item itself was and stay visible. Will be removed as soon as the change animation is finished.

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.

Related Topic: A new subpage is planned on the Gridzy website. On this subpage, customers present their own creation. If you want to present your creation too, just get in touch and send your link. It doesn’t have to be spectacular.

Optimize Loading

If you use many images, it could be a good idea to help Gridzy building the grid faster.

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. It is important to set the correct values for each individual image, otherwise the images would be distorted. The correct values are the original width and height of the respective image:

<div class="gridzy">
  <img src="https://loremflickr.com/640/480?random=1" width="640" height="480" alt="a random image" />
  <img src="https://loremflickr.com/480/640?random=2" width="480" height="640" alt="another random image" />
  <img src="https://loremflickr.com/640/640?random=3" width="640" height="640" alt="yet another random image" />
  <img src="https://loremflickr.com/640/480?random=4" width="640" height="480" alt="a random image again" />
  <img src="https://loremflickr.com/640/480?random=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:

Insert width and height attributes as described above (make sure to use the correct values)
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://loremflickr.com/640/480?random=1" width="640" height="480" alt="a random image" />
  <img data-gridzylazysrc="https://loremflickr.com/480/640?random=2" width="480" height="640" alt="another random image" />
  <img data-gridzylazysrc="https://loremflickr.com/640/640?random=3" width="640" height="640" alt="yet another random image" />
  <img data-gridzylazysrc="https://loremflickr.com/640/480?random=4" width="640" height="480" alt="a random image again" />
  <img data-gridzylazysrc="https://loremflickr.com/640/480?random=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.

Process Indicator

The process indicator is the small animated icon that appears while the image is loading. If you use captions & skins, the process indicator will be shown automatically. Otherwise you need some adjustments:

Put each img element into a div element
(or into any other element – see semantic HTML for more)
Add the class gridzyImage to each img element

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

After that you should see the process indicators if the images take time to load.

Filters

Filters in Gridzy 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://loremflickr.com/640/480/animals?random=1" alt="a random animal image" />
  <img class="architecture" src="https://loremflickr.com/640/480/arch?random=1" alt="a random architecture image" />
  <img class="people" src="https://loremflickr.com/640/480/people?random=1" alt="a random people image" />
  <img class="animals" src="https://loremflickr.com/640/480/animals?random=2" alt="another random animal image" />
  <img class="architecture" src="https://loremflickr.com/640/480/arch?random=2" alt="another random architecture image" />
  <img class="people" src="https://loremflickr.com/640/480/people?random=2" alt="another random people image" />
  <img class="animals" src="https://loremflickr.com/640/480/animals?random=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://loremflickr.com/640/480/animals?random=1" alt="a random animal image" />
  <img class="architecture" src="https://loremflickr.com/640/480/arch?random=1" alt="a random architecture image" />
  <img class="people" src="https://loremflickr.com/640/480/people?random=1" alt="a random people image" />
  <img class="animals" src="https://loremflickr.com/640/480/animals?random=2" alt="another random animal image" />
  <img class="architecture" src="https://loremflickr.com/640/480/arch?random=2" alt="another random architecture image" />
  <img class="people" src="https://loremflickr.com/640/480/people?random=2" alt="another random people image" />
  <img class="animals" src="https://loremflickr.com/640/480/animals?random=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://loremflickr.com/640/480/animals?random=1" alt="a random animal image" />
  <img class="architecture" src="https://loremflickr.com/640/480/arch?random=1" alt="a random architecture image" />
  <img class="people" src="https://loremflickr.com/640/480/people?random=1" alt="a random people image" />
  <img class="animals" src="https://loremflickr.com/640/480/animals?random=2" alt="another random animal image" />
  <img class="architecture" src="https://loremflickr.com/640/480/arch?random=2" alt="another random architecture image" />
  <img class="people" src="https://loremflickr.com/640/480/people?random=2" alt="another random people image" />
  <img class="animals" src="https://loremflickr.com/640/480/animals?random=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://loremflickr.com/640/480/animals?random=1" alt="a random animal image" />
  <img class="architecture" src="https://loremflickr.com/640/480/arch?random=1" alt="a random architecture image" />
  <img class="people" src="https://loremflickr.com/640/480/people?random=1" alt="a random people image" />
  <img class="animals" src="https://loremflickr.com/640/480/animals?random=2" alt="another random animal image" />
  <img class="architecture" src="https://loremflickr.com/640/480/arch?random=2" alt="another random architecture image" />
  <img class="people" src="https://loremflickr.com/640/480/people?random=2" alt="another random people image" />
  <img class="animals" src="https://loremflickr.com/640/480/animals?random=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!

If you prefer a JavaScript solution, check out the API.

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://loremflickr.com/640/480';

// 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

DEPRECATED since version 2.4.0
Use the modern and more flexible Events instead. See the next section for details.

~~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.
  }
});

	~~Description~~
~~onBeforeOptionsChanged~~	~~Callback function that is invoked directly before setting options.~~
~~onOptionsChanged~~	~~Callback function that is invoked directly after setting options.~~
~~onBeforeRender~~	~~Callback function that is invoked directly before rendering.~~
~~onRender~~	~~Callback function that is invoked directly after rendering.~~

Use Events

since version 2.4.0

You can use Gridzy events exactly like usual JavaScript events:

document.addEventListener('gridzyOptionsChanged', function(event) {
    // will be executed each time the options have changed.
});

document.addEventListener('gridzyBeforeOptionsChanged', function(event) {
    // will be executed, before new options take effect.
});

Some events are fired on the Gridzy container element and other events are fired on the individual item elements within the container element.

Events fired on the Gridzy container element:

	Description
gridzyBeforeInit	Fires before gallery initialization.
gridzyInit	Fires after gallery initialization.
gridzyBeforeOptionsChanged	Fires before setting options.
gridzyOptionsChanged	Fires after setting options.
gridzyBeforeRender	Fires before rendering.
gridzyRender	Fires after rendering.

If you miss any events here, please send a support request.

event.target provides the Gridzy container element.
event.detail.instance provides the Gridzy instance.

Events fired on item elements:

	Description
gridzyItemBeforeInit	Fires before item initialization.
gridzyItemInit	Fires after item initialization.
gridzyItemLoading	Fires when the item starts loading.
gridzyItemReady	Fires when the item is ready for grid calculation. So the aspect ratio is known, but the image may still be loading.
gridzyItemComplete	Fires when the item image is fully loaded.

If you miss any events here, please send a support request.

event.target provides the respective item element.
event.detail.instance provides the Gridzy instance.

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,
  autoSyncImageMutation: false
});

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

	Default Value	Description
autoInitOnDomReady	`true`	Detects elements with class `gridzy` on page loading and initializes them. Settable via `Gridzy.setDefaultOptions()`
autoInitOnDomMutation MutationObserver	`true`	Detects new elements with class `gridzy` as soon as they appear in the DOM and initializes them. (e.g. on using page transitions) Settable via `Gridzy.setDefaultOptions()`
autoSyncChildListMutation MutationObserver	`true`	Detects whether child elements (images) are added or removed, and updates the grid automatically. Settable via `data-grizy-`, `new Gridzy()`, `setOptions()`, `Gridzy.setDefaultOptions()`
useOptionAttributes	`true`	Defines whether the `data-gridzy-` attributes are generally used or not. If this is `false` options can be set only via the proprietary API. Settable via `new Gridzy()`, `setOptions()`, `Gridzy.setDefaultOptions()`
autoSyncAttributesMutation MutationObserver	`true`	Detects changes of `data-gridzy-` attributes, and updates the grid automatically. Also detects if the `gridzyAnimated` class is added or removed and if `style` attribute changes occur. If `useOptionAttributes` is `false`, it detects only `style` attribute changes. Settable via `data-grizy-`, `new Gridzy()`, `setOptions()`, `Gridzy.setDefaultOptions()`
autoSyncChildClassMutation MutationObserver	`true`	Detects changes of `class` attributes of all child elements (images). Relevant regarding filters. Settable via `data-grizy-`, `new Gridzy()`, `setOptions()`, `Gridzy.setDefaultOptions()`
autoSyncImageMutation MutationObserver since version 2.5.0	`true`	Detects changes of `src` attributes of all images. Relevant when used with React or similar libraries. Settable via `data-grizy-`, `new Gridzy()`, `setOptions()`, `Gridzy.setDefaultOptions()`
autoRenderOnResize ResizeObserver since version 2.6.0	`true`	Detects changes of the element width. Relevant regarding responsive design. (Before version 2.6.0 a window resize event listener was used) Settable via `data-grizy-`, `new Gridzy()`, `setOptions()`, `Gridzy.setDefaultOptions()`

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();