Magic Grid

You can install Magic Grid via NPM or include it directly in your HTML using a CDN.

npm install magic-grid

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

<!-- Minified CDN -->
<script src="https://unpkg.com/magic-grid/dist/magic-grid.min.js"></script>

Depending on your environment, import the library using ES modules or CommonJS.

import MagicGrid from "magic-grid"

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

Use the static: true option if all child elements of your container are already present in the DOM and do not change dynamically.

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

If your container loads content from an API or experiences rendering delays, you must provide the items count to let the grid know how many 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();

The MagicGrid constructor initializes the grid with a configuration object.

Note: Every item in the grid must have the same width.

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, // Optional. Maximum number of columns. Default: Infinite.
  useMin: true, // Optional. Prioritize shorter columns when positioning items? Default: false.
  useTransform: true, // Optional. Position items using CSS transform? Default: True.
  animate: true, // Optional. Animate item positioning? Default: false.
  center: true, // Optional. Center the grid items? Default: true. 
});

MagicGrid(config)

Initializes the grid with a configuration object.

.listen()

Positions the items and listens for changes to the window size. All items are repositioned whenever the window is resized. The library also listens for changes in container size.

.positionItems()

Manually triggers a repositioning of items. Useful when new elements are added to the container.

.onReady(callback)

Adds a listener that executes a function once the grid is ready. Returns a unique ID.

.onPositionComplete(callback)

Adds a listener that executes a function whenever positionItems is called (including initial setup and window/container resizing). Returns a unique ID.

.removeListener(id)

Removes a listener by its unique ID.

MagicGrid provides two primary lifecycle events that you can subscribe to using callback functions:

• onReady(callback): Triggered when the grid determines all expected items (defined by the items config) are present in the DOM.
• onPositionComplete(callback): Triggered after the items have been successfully positioned in the grid.

These methods return the result of the underlying addListener call.

Call listen() to begin the grid's operation. This method:

1. Checks if the grid is ready() (all items loaded).
2. If not ready, it starts a polling interval to check for items.
3. If ready, it attaches a resize event listener to the window, initializes a ResizeObserver for the container, and performs the initial positionItems() call.
4. Emits the READY_EVENT once initialized.

Removes a previously registered listener using its unique ID returned by .onReady() or .onPositionComplete().

magicGrid.removeListener(id);

Adds a listener that executes a callback function once the grid is ready. Returns a unique id that can be used to remove the listener.

const id = magicGrid.onReady(() => {
  console.log("Grid is ready");
});