Foundation
Jump to Nav

# Equalizer

JavaScript

Equalizer makes it dead simple to give multiple items equal height.

## Basics

To set up an Equalizer group, you need a container, which gets the attribute `data-equalizer`, and then a series of child elements, which get the attribute `data-equalizer-watch`. The child elements will all be resized to have the same height.

    <div class="row" data-equalizer data-equalize-on="medium" id="test-eq">
      <div class="medium-4 columns">
        <div class="callout" data-equalizer-watch>
          <img src= "assets/img/generic/square-1.jpg">
        </div>
      </div>
      <div class="medium-4 columns">
        <div class="callout" data-equalizer-watch>
          <p>Pellentesque habitant morbi tristique senectus et netus et, ante.</p>
        </div>
      </div>
      <div class="medium-4 columns">
        <div class="callout" data-equalizer-watch>
          <img src= "assets/img/generic/rectangle-1.jpg">
        </div>
      </div>
    </div>

Pellentesque habitant morbi tristique senectus et netus et, ante.

## Nesting

To use one Equalizer inside another, each container needs a unique ID, assigned with the `data-equalizer` attribute. Each `data-equalizer-watch` element should then have a value that matches its parent.

In the below example, the first set of Equalizer elements have the value `foo`, while the inside elements have the value `bar`. In the live example, we've also set the `equalizeOn` option to 'medium' for the parent elements, and the child Equalizer contained in the first div equalizes on stack, and maintains equal height.

    <div class="row" data-equalizer="foo">
      <div class="medium-4 columns" data-equalizer-watch="foo">
        <div class="callout" data-equalizer="bar">
          <h3>Parent panel</h3>
          <div class="callout" data-equalizer-watch="bar"></div>
          <div class="callout" data-equalizer-watch="bar"></div>
          <div class="callout" data-equalizer-watch="bar"></div>
        </div>
      </div>
      <div class="medium-4 columns">
        <div class="callout panel" data-equalizer-watch="foo"></div>
      </div>
      <div class="medium-4 columns">
        <div class="callout" data-equalizer-watch="foo"></div>
      </div>
    </div>

### Parent panel

The three callouts in this panel will equalize, even when stacked.

Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante.

Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante.

Where these panels will not equalize on stack, and instead equalize on medium up.

Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante.

## Equalize By Row

If you have a gallery of items that wrap multiple times, Equalizer can be configured to match each row's items in height. Works great with the block grid!

Under the Hood:

Equalizer splits the `data-equalizer-watch` elements into groups by checking their vertical offsets, and grouping ones with the same offset into a "row".

Be aware on what you set `data-equalizer-watch`, if the top position is different, Equalizer will interpret that as a new "row" and equalize accordingly.

    <div class="row small-up-1 medium-up-2 large-up-4" data-equalizer data-equalize-by-row="true">
      <div class="column" data-equalizer-watch></div>
      <div class="column" data-equalizer-watch></div>
      <div class="column" data-equalizer-watch></div>
      <!-- ... -->
    </div>

Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet

## JavaScript Reference

### Initializing

The file `foundation.equalizer.js` must be included in your JavaScript to use this plugin, along with `foundation.core.js`. This plugin also requires these utility libraries:

- `foundation.util.mediaQuery.js`

- `foundation.util.timerAndImageLoader.js`

### Foundation.Equalizer

Creates a new instance of Equalizer.

    var elem = new Foundation.Equalizer(element, options);

Fires these events: Equalizer#event:init

Name | Type | Description
--- | --- | ---
`element` | Object | jQuery object to add the trigger to.
`options` | Object | Overrides to the default plugin settings.

### Plugin Options

Use these options to customize an instance of Equalizer. Plugin options can be set as individual data attributes, one combined `data-options` attribute, or as an object passed to the plugin's constructor. Learn more about how JavaScript plugins are initialized.

Name | Type | Default | Description
--- | --- | --- | ---
`data-equalize-on-stack` | `boolean` | `false` | Enable height equalization when stacked on smaller screens.
`data-equalize-by-row` | `boolean` | `false` | Enable height equalization row by row.
`data-equalize-on` | `string` | `''` | String representing the minimum breakpoint size the plugin should equalize heights on.

### Events

These events will fire from any element with a Equalizer plugin attached.

Name | Description
--- | ---
`preequalized.zf.equalizer` | Fires before the heights are applied
`postequalized.zf.equalizer` | Fires when the heights have been applied
`preequalizedrow.zf.equalizer` | Fires before the heights per row are applied
`postequalizedrow.zf.equalizer` | Fires when the heights per row have been applied

### Methods

#### getHeights

    $('#element').foundation('getHeights', cb);

Finds the outer heights of children contained within an Equalizer parent and returns them in an array

Name | Type | Description
--- | --- | ---
`cb` | function | A non-optional callback to return the heights array to.

#### getHeightsByRow

    $('#element').foundation('getHeightsByRow', cb);

Finds the outer heights of children contained within an Equalizer parent and returns them in an array

Name | Type | Description
--- | --- | ---
`cb` | function | A non-optional callback to return the heights array to.

#### applyHeight

    $('#element').foundation('applyHeight', heights);

Changes the CSS height property of each child in an Equalizer parent to match the tallest

Fires these events: Equalizer#event:preequalized Equalizer#event:postequalized

Name | Type | Description
--- | --- | ---
`heights` | array | An array of heights of children within Equalizer container

#### applyHeightByRow

    $('#element').foundation('applyHeightByRow', groups);

Changes the CSS height property of each child in an Equalizer parent to match the tallest by row

Fires these events: Equalizer#event:preequalized Equalizer#event:preequalizedrow Equalizer#event:postequalizedrow Equalizer#event:postequalized

Name | Type | Description
--- | --- | ---
`groups` | array | An array of heights of children within Equalizer container grouped by row with element,height and max as last child

#### destroy

    $('#element').foundation('destroy');

Destroys an instance of Equalizer.