A matrix is a type of grid that re-arranges items into an optimal position based on vertical and horizontal space — also known as a masonry grid. The matrix takes into account gutter spacing, inline images, multiple spanning columns, and much more.

To begin, the matrix markup requires an unordered list. Each item in the list can use custom markup, but will require a fixed width (defined by the width option).

<ul class="matrix">
    <li><!-- Item content --></li>

Once the markup is in place, the matrix can be initialized.


Adding & Removing Items

To add or remove items after the matrix has rendered, we can use append(), prepend(), and remove(). But first, we need to fetch the instantiated matrix object.

var matrix = $('.matrix').toolkit('matrix');

When adding items to the matrix, the element being added must be an li, or a jQuery object representing an li.

var li = document.createElement('li');
// Add content to the li


When removing an item, an element that is currently within the matrix must be passed to remove().

var li = $('.matrix').find('li:eq(10)');

// Remove it

// Equivalent to

Fluid Images

When columns are rendered, their widths may fluctuate a few pixels to scale accordingly. Because of this, fixed width images may render incorrectly, or just look off. We suggest adding .fluid from the base CSS to all inline images.

    <img src="/img/banner.png" class="fluid">


  • The wrapper will have .no-columns added when the viewport is too small for multiple columns.
  • The matrix will automatically re-render when the viewport is resized.


Variable Default Description
$matrix-class .matrix CSS class name for the matrix list.
$matrix-transition .3s The transition time for matrix item position animations.


Inherits all options from the parent Component.

Option Type Default Description
defer bool true Defer positioning of items until all images within the items have loaded. If this is false, items may overlap once images load after the fact.
gutter int 20 The margin between each item and or column.
rtl bool Toolkit.isRTL Render items in reverse order for right-to-left languages.
width int 200 The virtual column width to align all items against. Larger items may span multiple columns.


Inherits all events from the parent Component.

Event Arguments Description
appending element:item Triggered before an element is appended to the matrix.
prepending element:item Triggered before an element is prepended to the matrix.
removing element:item Triggered before an element is removed from the matrix.
rendering Triggered before the matrix is rendered. This can happen on initialization, refresh, or appending, prepending, and removing of items.
rendered Triggered after the matrix is rendered.


Inherits all properties from the parent Component.

Property Type Description Found With
colCount int The number of columns that can fit within the current wrapper width.
colHeights array The current height of each column.
colWidth int The calculated width of each column based on the width option.
images collection A collection of imgs found within matrix items. Is used for deferred loading. img
items collection A collection of elements to position in the grid. > li
matrix array List of items organized in render order with column span detection flags.
wrapperWidth int The width of the matrix wrapper.


Inherits all methods from the parent Component.

Method Description
append(element:item) Append an item to the matrix and re-render. The item must be an li.
prepend(element:item) Prepend an item to the matrix and re-render. The item must be an li.
refresh() Refresh the items list and re-render. This method is automatically called from other methods.
remove(element:item) Remove an item from the matrix and re-render. The element must match an existing item in the matrix.
render() Render the items into a uniform grid. This method is called automatically.