Foundation
Jump to Nav

# Dropdown

JavaScript

Dropdown panes are little happy sprites which can be revealed on click or hover.

You might be looking for dropdown menus, which are a separate plugin.

## Basics

To create a dropdown pane, add the class `.dropdown-pane` and the attribute `data-dropdown` to an element. Give the dropdown a unique ID as well.

To create the dropdown trigger, add `data-toggle` to a `<button>`. The value of `data-toggle` is the ID of the dropdown.

    <button class="button" type="button" data-toggle="example-dropdown">Toggle Dropdown</button>
    <div class="dropdown-pane" id="example-dropdown" data-dropdown data-auto-focus="true">
      Example form in a dropdown.
      <form>
        <div class="row">
          <div class="medium-6 columns">
            <label>Name
              <input type="text" placeholder="Kirk, James T.">
            </label>
          </div>
          <div class="medium-6 columns">
            <label>Rank
              <input type="text" placeholder="Captain">
            </label>
          </div>
        </div>
      </form>
    </div>

    <button class="button" type="button" data-toggle="example-dropdown-1">Hoverable Dropdown</button>
    <div class="dropdown-pane" id="example-dropdown-1" data-dropdown data-hover="true" data-hover-pane="true">
      Just some junk that needs to be said. Or not. Your choice.
    </div>

Example form in a dropdown.
Name
Rank
Just some junk that needs to be said. Or not. Your choice.

## Positioning

By default, a dropdown anchors below the button that opened it. Add the class `.top`, `.right`, or `.bottom` to the dropdown to change this.

    <button class="button" type="button" data-toggle="example-dropdown2">Top Aligned</button>

    <div class="dropdown-pane top" id="example-dropdown2" data-dropdown>
      Just some junk that needs to be said. Or not. Your choice.
    </div>

Just some junk that needs to be said. Or not. Your choice.

Just some junk that needs to be said. Or not. Your choice.

Just some junk that needs to be said. Or not. Your choice.

Adding `.float-right` or `.float-left` to the anchor will change the direction of the dropdown as well.

Just some junk that needs to be said. Or not. Your choice.

Just some junk that needs to be said. Or not. Your choice.

## Sass Reference

### Variables

The default styles of this component can be customized using these Sass variables in your project's settings file.

Name | Type | Default Value | Description
--- | --- | --- | ---
`$dropdown-padding` | List | `1rem` | Padding for dropdown panes.
`$dropdown-background` | Color | `$body-background` | Background for dropdown panes.
`$dropdown-border` | List | `1px solid $medium-gray` | Border for dropdown panes.
`$dropdown-font-size` | List | `1rem` | Font size for dropdown panes.
`$dropdown-width` | Number | `300px` | Width for dropdown panes.
`$dropdown-radius` | Number | `$global-radius` | Border radius dropdown panes.
`$dropdown-sizes` | Map | `tiny: 100px small: 200px large: 400px` | Sizes for dropdown panes. Each size is a CSS class you can apply.

### Mixins

We use these mixins to build the final CSS output of this component. You can use the mixins yourself to build your own class structure out of our components.

#### dropdown-container

    @include dropdown-container;

Applies styles for a basic dropdown.

## JavaScript Reference

### Initializing

The file `foundation.dropdown.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.box.js`

- `foundation.util.triggers.js`

### Foundation.Dropdown

Creates a new instance of a dropdown.

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

Name | Type | Description
--- | --- | ---
`element` | jQuery | jQuery object to make into a dropdown. Object should be of the dropdown panel, rather than its anchor.
`options` | Object | Overrides to the default plugin settings.

### Plugin Options

Use these options to customize an instance of Dropdown. 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-parent-class` | `string` | `null` | Class that designates bounding container of Dropdown (default: window)
`data-hover-delay` | `number` | `250` | Amount of time to delay opening a submenu on hover event.
`data-hover` | `boolean` | `false` | Allow submenus to open on hover events
`data-hover-pane` | `boolean` | `false` | Don't close dropdown when hovering over dropdown pane
`data-v-offset` | `number` | `1` | Number of pixels between the dropdown pane and the triggering element on open.
`data-h-offset` | `number` | `1` | Number of pixels between the dropdown pane and the triggering element on open.
`data-position-class` | `string` | `''` | Class applied to adjust open position. JS will test and fill this in.
`data-trap-focus` | `boolean` | `false` | Allow the plugin to trap focus to the dropdown pane if opened with keyboard commands.
`data-auto-focus` | `boolean` | `false` | Allow the plugin to set focus to the first focusable element within the pane, regardless of method of opening.
`data-close-on-click` | `boolean` | `false` | Allows a click on the body to close the dropdown.

### Events

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

Name | Description
--- | ---
`closeme.zf.dropdown` | Fires to close other open dropdowns, typically when dropdown is opening
`show.zf.dropdown` | Fires once the dropdown is visible.
`hide.zf.dropdown` | Fires once the dropdown is no longer visible.

### Methods

#### getPositionClass

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

Helper function to determine current orientation of dropdown pane.

#### open

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

Opens the dropdown pane, and fires a bubbling event to close other dropdowns.

Fires these events: Dropdown#event:closeme Dropdown#event:show

#### close

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

Closes the open dropdown pane.

Fires these events: Dropdown#event:hide

#### toggle

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

Toggles the dropdown pane's visibility.

#### destroy

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

Destroys the dropdown.