Dropdown
JavaScriptDropdown 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
<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.
<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
This dropdown has position bottom and alignment left should align with its top left corner at the bottom left of the button
Bottom Center
This dropdown has position bottom and alignment center should align below the button with its center aligned with the center of the button
Bottom Right
This dropdown has position bottom and alignment right should align with its top right corner at the bottom right of the button
Top Left
This dropdown has position top and alignment left should align with its bottom left corner at the top left of the button
Top Center
This dropdown has position top and alignment center should align above with its center aligned with the center of the button
Top Right
This dropdown has position top and alignment right should align with its bottom right corner at the top right of the button
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
This dropdown has position right and alignment top should align with its top left corner at the top right of the button
Left Top
This dropdown has position left and alignment top should align with its top right corner at the top left of the button
Right Center
This dropdown has position right and alignment center should align to the right of the button with the center of the dropdown vertically aligned with the center of the button
Left Center
This dropdown has position left and alignment center should align to the left of the button with the center of the dropdown vertically aligned with the center of the button
Right Bottom
This dropdown has position right and alignment bottom should align with its bottom left corner at the bottom right of the button
Left Bottom
This dropdown has position left and alignment bottom should align with its bottom right corner at the bottom left of the button
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 |
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 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
- With utility library
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 |
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.
| 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
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.