macy.js

The breakAt option allows you to change the number of columns and margins at specific viewport widths. When the viewport resizes, Macy automatically reruns to optimize the layout.

Changing columns and margins:

{
  breakAt: {
    760: {
      margin: {
        x: 20,
        y: 10,
      },
      columns: 4
    }
  }
}

Changing only one margin direction:

{
  breakAt: {
    760: {
      margin: {
        x: 20,
      },
      columns: 4
    }
  }
}

You can install Macy.js using npm, Bower, or by including it via a CDN.

npm install macy

bower install macy

<script src="https://cdn.jsdelivr.net/npm/macy@2"></script>

To use Macy.js, call the Macy() function with a configuration object. The container property is required and should be a CSS selector for the element containing the items you want to sort.

var macyInstance = Macy({
  container: '#macy-container',
  trueOrder: false,
  waitForImages: false,
  margin: 24,
  columns: 6,
  breakAt: {
    1200: 5,
    940: 3,
    520: 2,
    400: 1
  }
});

Use recalculate() to force Macy to re-run the layout logic. This is useful when content is added dynamically (e.g., via AJAX).

macyInstance.recalculate();

To ensure the layout is correct when images load (especially with AJAX), use runOnImageLoad().

• Run on every image load: Pass a callback and true as the second argument.
• Run once after all images load: Pass a callback and omit the second argument (defaults to false).

The callback receives an event object. If running on every load, event.data.img contains the image that just loaded (may be undefined on the final completion event).

Example: Recalculate on every image load:

macyInstance.runOnImageLoad(function (event) {
  if (event.data.img) {
    // note: this parameter can be undefined if it is the final completion event that is emitted.
    console.log(event.data.img);
  }
  macyInstance.recalculate(true);
}, true);

You can listen to specific lifecycle events using the on(eventKey, callback) method. Use the constants provided on the instance to ensure accuracy.

macyInstance.on(macyInstance.constants.EVENT_IMAGE_COMPLETE, function (ctx) {
  console.log('all images have loaded');
});

Use remove() to strip all styling and event listeners added by Macy from the DOM. Use reInit() to re-initialize the current instance.

macyInstance.remove();

macyInstance.reInit();

Access these constants via macyInstance.constants to avoid hardcoding event strings.

| Key | Value | Description |
|----------------------|----------------------|----------------------|
| EVENT_INITIALIZED | `'macy.initialized'` | This is the event constant for when macy is initialized/reinitialized |
| EVENT_RECALCULATED | `'macy.recalculated'` | This is the event constant for every time the layout is recalculated |
| EVENT_IMAGE_LOAD | `'macy.images.load'` | This is the event constant for when an image loads |
| EVENT_IMAGE_COMPLETE | `'macy.images.complete'` | This is the event constant for when all images are complete |
| EVENT_RESIZE | `'macy.resize'` | This is the event constant for when the document is resized |