Magic Grid

A simple, lightweight Javascript library for dynamic grid layouts.

Creating a dynamic grid layout has never been easier. With Magic Grid, all you have to do is specify a container and listen for changes. A few other configuration options are available for convenience but it's all very simple.

Magic-Gridv

View Demo Download Source

Getting Started

Step 1

Get Magic Grid via NPM:

npm install magic-grid

Or CDN

<script src="https://unpkg.com/magic-grid/dist/magic-grid.cjs.js"></script>

<!-- or (minified) -->
<script src="https://unpkg.com/magic-grid/dist/magic-grid.min.js"></script>

Step 2 (skip if using CDN)

Import Magic Grid:

import MagicGrid from "magic-grid"

// or
let MagicGrid = require("magic-grid");

You can also pull Magic Grid directly into your html

<script src="node_modules/magic-grid/dist/magic-grid.cjs.js"></script>

<!-- or (minified) -->
<script src="node_modules/magic-grid/dist/magic-grid.min.js"></script>

Step 3

You're good to go! If you used a script tag, the library can be referenced via the global variable, MagicGrid.

let magicGrid = new MagicGrid(...);

magicGrid.listen();

Usage

Static content:

If your container doesn't have any dynamically loaded content i.e., all its child elements are always in the DOM, you should initialize the grid this way:

let magicGrid = new MagicGrid({
  container: "#container", // Required. Can be a class, id, or an HTMLElement.
  static: true, // Required for static content.
  animate: true, // Optional.
});

magicGrid.listen();

Dynamic content:

If the container relies on data from an api, or experiences a delay, for whatever reason, before it can render its content in the DOM, you need to let the grid know the number of items to expect:

let magicGrid = new MagicGrid({
  container: "#container", // Required. Can be a class, id, or an HTMLElement.
  items: 20, // For a grid with 20 items. Required for dynamic content.
  animate: true, // Optional.
});

magicGrid.listen();

API

MagicGrid(config)

config (required): Configuration object

The MagicGrid constructor. Initializes the grid with a configuration object.

let magicGrid = new MagicGrid({
  container: "#container", // Required. Can be a class, id, or an HTMLElement
  static: false, // Required for static content. Default: false.
  items: 30, // Required for dynamic content. Initial number of items in the container.
  gutter: 30, // Optional. Space between items. Default: 25(px).
  maxColumns: 5, // Maximum number of columns. Default: Infinite.
  useMin: true, // Prioritize shorter columns when placing items in the grid. Default: false.
  animate: true, // Animate item positioning. Default: false.
});

.listen()

Positions the items and listens for changes to the window size. All items are repositioned whenever the window is resized.

let magicGrid = new MagicGrid({
  container: "#container", // Required. Can be a class, id, or an HTMLElement
  static: true, // Required for static content.
  animate: true, // Optional.
});

magicGrid.listen();

.positionItems()

This function is useful in cases where you have to manually trigger a repositioning; for instance, if a new element is added to the container.

let magicGrid = new MagicGrid({
  container: "#container", // Required. Can be a class, id, or an HTMLElement
  items: 30, // Required for dynamic content.
  animate: true, // Optional
});

magicGrid.listen();

// get data from api
// append new element to DOM

// reposition items
magicGrid.positionItems();

GitHub