Foundation
Jump to Nav

# Drilldown

JavaScript

Drilldown is one of Foundation's three menu patterns, which converts a series of nested lists into a vertical drilldown menu.

## Basics

Drilldowns use the standard Menu syntax, using `<ul>`, `<li>`, and `<a>`. Add `data-drilldown` to the root menu to set up the drilldown.

To create sub-menus, place a `<ul>` next to an `<a>`. Clicking that `<a>` will then open the `<ul>` that it's next to.

Any `<a>` without a submenu will function like a normal link.

    <ul class="vertical menu" data-drilldown>
      <li>
        <a href="#Item-1">Item 1</a>
        <ul class="vertical menu">
          <li><a href="#Item-1A">Item 1A</a></li>
          <!-- ... -->
        </ul>
      </li>
      <li><a href="#Item-2">Item 2</a></li>
    </ul>

The drilldown menu takes on the height of the tallest menu in the hierarchy, so the menu doesn't change height as the user navigates it.

## autoHeight

If you like to set the height to auto you can also set the autoHeight and animateHeight params

## ScrollTop Drilldown

Scroll to the top of the menu when selecting a submenu/navigating back using the menu back button. Can be useful with a longer menu to provide a better user experience.

## Custom Styling

The drilldown plugin automatically adds a back button to the top of each nested menu. To style this control, target the `.js-drilldown-back` class:

    .js-drilldown-back {
      // ...
    }

## JavaScript Reference

### Initializing

The file `foundation.drilldown.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.keyboard.js`

- `foundation.util.motion.js`

- `foundation.util.nest.js`

### Foundation.Drilldown

Creates a new instance of a drilldown menu.

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

Name | Type | Description
--- | --- | ---
`element` | jQuery | jQuery object to make into an accordion menu.
`options` | Object | Overrides to the default plugin settings.

### Plugin Options

Use these options to customize an instance of Drilldown. 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-back-button`

`string`

`
- Back
`

Markup used for JS generated back button. Prepended or appended (see backButtonPosition) to submenu lists and deleted on `destroy` method, 'js-drilldown-back' class required. Remove the backslash (`\`) if copy and pasting.

`data-back-button-position` | `string` | `top` | Position the back button either at the top or bottom of drilldown submenus. Can be `'left'` or `'bottom'`.
`data-wrapper` | `string` | `` | Markup used to wrap drilldown menu. Use a class name for independent styling; the JS applied class: `is-drilldown` is required. Remove the backslash (`\`) if copy and pasting.
`data-parent-link` | `boolean` | `false` | Adds the parent link to the submenu.
`data-close-on-click` | `boolean` | `false` | Allow the menu to return to root list on body click.
`data-auto-height` | `boolean` | `false` | Allow the menu to auto adjust height.
`data-animate-height` | `boolean` | `false` | Animate the auto adjust height.
`data-scroll-top` | `boolean` | `false` | Scroll to the top of the menu after opening a submenu or navigating back using the menu back button
`data-scroll-top-element` | `string` | `''` | String jquery selector (for example 'body') of element to take offset().top from, if empty string the drilldown menu offset().top is taken
`data-scroll-top-offset` | `number` | `0` | ScrollTop offset
`data-animation-duration` | `number` | `500` | Scroll animation duration
`data-animation-easing` | `string` | `swing` | Scroll animation easing. Can be `'swing'` or `'linear'`.

### Events

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

Name | Description
--- | ---
`scrollme.zf.drilldown` | Fires after the menu has scrolled
`closed.zf.drilldown` | Fires when the menu is fully closed.
`open.zf.drilldown` | Fires when the submenu has opened.
`hide.zf.drilldown` | Fires when the submenu has closed.

### Methods

#### _scrollTop

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

Scroll to Top of Element or data-scroll-top-element

Fires these events: Drilldown#event:scrollme

#### _hideAll

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

Closes all open elements, and returns to root menu.

Fires these events: Drilldown#event:closed

#### _back

    $('#element').foundation('_back', $elem);

Adds event listener for each `back` button, and closes open menus.

Fires these events: Drilldown#event:back

Name | Type | Description
--- | --- | ---
`$elem` | jQuery | the current sub-menu to add `back` event.

#### _show

    $('#element').foundation('_show', $elem);

Opens a submenu.

Fires these events: Drilldown#event:open

Name | Type | Description
--- | --- | ---
`$elem` | jQuery | the current element with a submenu to open, i.e. the `li` tag.

#### _hide

    $('#element').foundation('_hide', $elem);

Hides a submenu

Fires these events: Drilldown#event:hide

Name | Type | Description
--- | --- | ---
`$elem` | jQuery | the current sub-menu to hide, i.e. the `ul` tag.

#### destroy

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

Destroys the Drilldown Menu