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.

Watch this part in video

edit on codepen button
<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="grid-container">
      <div class="grid-x grid-margin-x">
        <div class="cell medium-6">
          <label>Name
            <input type="text" placeholder="Kirk, James T.">
          </label>
        </div>
        <div class="cell medium-6">
          <label>Rank
            <input type="text" placeholder="Captain">
          </label>
        </div>
      </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>

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.

edit on codepen button
<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>

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


Explicit Positioning

New in v6.4: Heads up! This explicit positioning model is a new feature in v6.4.

Wouldn't it be great if you can define both positions at the dropdown element. Dropdown has a fully explicit positioning model through which you can use both data-position and data-alignment to define both positions of the box.

These dropdowns test various positioning and alignments. Valid positions are left/right/top/bottom. Valid alignments are left/right/top/bottom/center. Left align means left sides should line up. Right align means right sides should line up. Center align means centers should line up.

Top and Bottom positioned

<!-- Bottom Left -->
<button class="button" type="button" data-toggle="example-dropdown-bottom-left">Toggle Dropdown</button>
<div class="dropdown-pane" data-position="bottom" data-alignment="left" id="example-dropdown-bottom-left" data-dropdown data-auto-focus="true">
  <!-- My dropdown content in here -->
</div>

<!-- Bottom Center -->
<button class="button" type="button" data-toggle="example-dropdown-bottom-center">Toggle Dropdown</button>
<div class="dropdown-pane" data-position="bottom" data-alignment="center" id="example-dropdown-bottom-center" data-dropdown data-auto-focus="true">
  <!-- My dropdown content in here -->
</div>

<!-- Bottom Right -->
<button class="button" type="button" data-toggle="example-dropdown-bottom-right">Toggle Dropdown</button>
<div class="dropdown-pane" data-position="bottom" data-alignment="right" id="example-dropdown-bottom-right" data-dropdown data-auto-focus="true">
  <!-- My dropdown content in here -->
</div>

<!-- Top Left -->
<button class="button" type="button" data-toggle="example-dropdown-top-left">Toggle Dropdown</button>
<div class="dropdown-pane" data-position="top" data-alignment="left" id="example-dropdown-top-left" data-dropdown data-auto-focus="true">
  <!-- My dropdown content in here -->
</div>

<!-- Top Center -->
<button class="button" type="button" data-toggle="example-dropdown-top-center">Toggle Dropdown</button>
<div class="dropdown-pane" data-position="top" data-alignment="center" id="example-dropdown-top-center" data-dropdown data-auto-focus="true">
  <!-- My dropdown content in here -->
</div>

<!-- Top Right -->
<button class="button" type="button" data-toggle="example-dropdown-top-right">Toggle Dropdown</button>
<div class="dropdown-pane" data-position="top" data-alignment="right" id="example-dropdown-top-right" data-dropdown data-auto-focus="true">
  <!-- My dropdown content in here -->
</div>

Bottom Left

Bottom Center

Bottom Right

Top Left

Top Center

Top Right


Left and Right Positioned

<!-- Right Top -->
<button class="button" type="button" data-toggle="example-dropdown-right-top">Toggle Dropdown</button>
<div class="dropdown-pane" data-position="right" data-alignment="top" id="example-dropdown-right-top" data-dropdown data-auto-focus="true">
</div>

<!-- Left Top -->
<button class="button" type="button" data-toggle="example-dropdown-left-top">Toggle Dropdown</button>
<div class="dropdown-pane" data-position="left" data-alignment="top" id="example-dropdown-left-top" data-dropdown data-auto-focus="true">
</div>

<!-- Right Center -->
<button class="button" type="button" data-toggle="example-dropdown-right-center">Toggle Dropdown</button>
<div class="dropdown-pane" data-position="right" data-alignment="center" id="example-dropdown-right-center" data-dropdown data-auto-focus="true">
</div>

<!-- Left Center -->
<button class="button" type="button" data-toggle="example-dropdown-left-center">Toggle Dropdown</button>
<div class="dropdown-pane" data-position="left" data-alignment="center" id="example-dropdown-left-center" data-dropdown data-auto-focus="true">
</div>

<!-- Right Bottom -->
<button class="button" type="button" data-toggle="example-dropdown-right-bottom">Toggle Dropdown</button>
<div class="dropdown-pane" data-position="right" data-alignment="bottom" id="example-dropdown-right-bottom" data-dropdown data-auto-focus="true">
</div>

<!-- Left Bottom -->
<button class="button" type="button" data-toggle="example-dropdown-left-bottom">Toggle Dropdown</button>
<div class="dropdown-pane" data-position="left" data-alignment="bottom" id="example-dropdown-left-bottom" data-dropdown data-auto-focus="true">
</div>

Right Top

Left Top

Right Center

Left Center

Right Bottom

Left Bottom


Sass Reference

Variables

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

NameTypeDefault ValueDescription
$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.

@include dropdown-container;

Applies styles for a basic dropdown.


JavaScript Reference

Initializing

The following files must be included in your JavaScript to use this plugin:

  • foundation.core.js
  • foundation.dropdown.js
    • With utility library foundation.util.keyboard.js
    • With utility library foundation.util.box.js
    • With utility library foundation.util.touch.js
    • With utility library foundation.util.triggers.js

Foundation.Dropdown

Creates a new instance of a dropdown.

var elem = new Foundation.Dropdown(element, options);
NameTypeDescription
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 0 Number of pixels between the dropdown pane and the triggering element on open.
data-h-offset number 0 Number of pixels between the dropdown pane and the triggering element on open.
data-position string auto Position of dropdown. Can be left, right, bottom, top, or auto.
data-alignment string auto Alignment of dropdown relative to anchor. Can be left, right, bottom, top, center, or auto.
data-allow-overlap boolean false Allow overlap of container/window. If false, dropdown will first try to position as defined by data-position and data-alignment, but reposition if it would cause an overflow.
data-allow-bottom-overlap boolean true Allow overlap of only the bottom of the container. This is the most common behavior for dropdowns, allowing the dropdown to extend the bottom of the screen but not otherwise influence or break out of the container.
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.
data-force-follow boolean true If true the default action of the toggle (e.g. follow a link with href) gets executed on click. If hover option is also true the default action gets prevented on first click for mobile / touch devices and executed on second click.

Events

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

NameDescription
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

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.