Basic Usage

1. Upload Gridzy Files

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

2. Add HTML Code

Add the HTML code to the body section. Every child element will be treated as its own sizing box. You can use any tag names for your code. The img-tag is not exchangeable and the main structure is important for predefined skins only. Be careful with elements that are already styled (such as the p-tag). You might have to adjust them for your specific use. Learn more about how to style Gridzy.

You will get access to the Gridzy Configurator for a straightforward usage right after your purchase.

3. Initialize Gridzy

Initialize Gridzy using one of the following code snippets. You can paste your choice at the end of the body tag for example (or at any other place where DOM is ready).

Initialization using jQuery

If your website uses jQuery you can initialize Gridzy with the following code snippet. Otherwise use one of the other code snippets below.

using jQuery
You will get access to the Gridzy Configurator for a straightforward usage right after your purchase.

Initialization without any other javascript library

You can initialize multiple instances by using the following code

standalone - multiple instances
You will get access to the Gridzy Configurator for a straightforward usage right after your purchase.

Or you can initialize a single instance by providing an element id. You have to set "gridzy" as the id of your containing element for the following example.

standalone - single instance
You will get access to the Gridzy Configurator for a straightforward usage right after your purchase.

Optimize Loading

Prevent initial Animation

If you are using the css class "gridzyAnimated", the elements will be animated always if they change there positions (if you resize the window for example). During the loading process the elements also get there new positions. To prevent this first animation, just set the option "preventInitialAnimation" on true.

using jQuery
standalone - single instance

Prevent jumping Images

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

To prevent such a behaviour set width and height attributes for all img-elements with the natural image dimensions:

Lazy Loading

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

  1. Set the option "preventInitialAnimation" on true like already described above. (yes, this is required)
  2. Insert width and height Attributes like also described above.
  3. Replace all src Attributes like following ...

Replace the "src" attributes of all img-tags with "data-gridzylazysrc" like you can see here:

After these three steps the images will load a little bit before they appear in the viewport.


The following properties are supported on the options object that you can pass to Gridzy.

Variable 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.
hideBoxOnMissingImage true Hides boxes that contain images that could not be loaded.
desiredElementHeight 150 Defines the desired height of element rows. The actual height will be computed depending on the available width and the elements in the row.
spaceBetweenElements 1 Defines the distance between elements in pixels.
preventInitialAnimation false Prevents the initial animation if the class "gridzyAnimated" is set.
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.

Smart Options

You can specify a custom javascript function to dynamically calculate the values of the desiredElementHeight and spaceBetweenElements properties. Gridzy will then use the value returned by the function when it renders the grid. For example, the following function could calculate the desired height based on the available width:

You can use the function instead of a constant value in the options object that you pass to Gridzy:

using jQuery


First you need to get the instance of Gridzy.

using jQuery

You can use the API thereafter.

Public Methods

Style Gridzy

You can change predefined styles or create your own. You just need to know a few things beforehand.

Study the HTML Structure

During initialization, Gridzy changes the structure of the HTML document. The following fragment

will change to

  1. There is a new div element with the class "gridzyContainer" which is inside the root element and contains all the content.
  2. Each item is wrapped in a new div element with the class "gridzyItem".
  3. Each of the original item elements has an additional class "gridzyItemContent".

An item's structure is slightly different during the loading process.

  1. The item has an additional class "gridzyItemLoading".
  2. A new div element with the class "gridzyItemProgressIndicator" will be inserted behind the origin item element.

Your style definitions should match these modified HTML structure. Otherwise the definitions might have undesired effects.

See a Few Styling Examples

Dare a look into Gridzy CSS File

Just open the file in your text editor. You will find a well-structured style sheet. Feel free to change, extend or reduce the definitions. To avoid the additional server request, you can paste the needed styles into your main css file of your website and omit the inclusion of Gridzy css file.

Mind Important Things

If you want to style the item contents, keep the following two things in mind:

  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 Gridzy option "autoFontSize" which binds the font-size onto the item box size.
  2. Every 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 could be easier to style the item contents before integrating Gridzy into your website.

Kindly leave your email address and I’ll notify you about new releases or updates.