zurb-foundation-5/doc/pages/components/dropdown.html

Foundation 5 for npm (no code modification from original repo)

---
title: Dropdowns
---

<h3 class="subheader">We removed the various dropdowns within different UI elements for Foundation 5. Instead, we created a universal dropdown plugin that will attach dropdowns or popovers to whatever element you need.</h3>

***

{{> examples_dropdown_basic}}

***

<h3>Basic</h3>

You can create a dropdown using minimal markup. <strong>On a small device, the tooltips are full-width and bottom aligned.</strong>

<div class="row">
  <div class="large-6 columns">
    <h4>HTML</h4>
{{> examples_dropdown_basic_rendered}}
  </div>
  <div class="large-6 columns">
    <h4>HTML Rendered</h4>
{{> examples_dropdown_basic_nostyle}}
  </div>
</div>

***

<h3>Advanced</h3>

Additional classes can be added to your dropdown to change its appearance.

<div class="row">
  <div class="large-6 columns">
    <h4>HTML</h4>
{{#markdown}}
```html
<a href="#" class="button" data-dropdown="drop">Link Dropdown &raquo;</a>
<ul id="drop" class="[tiny small medium large content]f-dropdown" data-dropdown-content>
  <li><a href="#">This is a link</a></li>
  <li><a href="#">This is another</a></li>
  <li><a href="#">Yet another</a></li>
</ul>
```
{{/markdown}}
  </div>
  <div class="large-6 columns">
    <h4>Rendered HTML</h4>
    <a href="#" class="button" data-dropdown="tinyDrop2">Link Dropdown &raquo;</a>
    <ul id="tinyDrop2" class="medium f-dropdown" data-dropdown-content>
      <li><a href="#">This is a link</a></li>
      <li><a href="#">This is another</a></li>
      <li><a href="#">Yet another</a></li>
    </ul>
  </div>
</div>

***

<h3>Directions</h3>

You can now position dropdowns on the top, bottom, left, or right of the target element. The default position is *bottom* and you do not need to change anything to get your tooltip positioned *bottom*.

To set other alignments, just specify the <code>align</code> property in <code>data-options</code> on the target element.
<div class="row">
  <div class="large-6 columns">
{{#markdown}}
```html
<a href="#" data-options="align:left" data-dropdown="drop" class="button">Link Dropdown &raquo;</a>
<ul id="drop" class="[tiny small medium large content]f-dropdown" data-dropdown-content>
  <li><a href="#">This is a link</a></li>
  <li><a href="#">This is another</a></li>
  <li><a href="#">Yet another</a></li>
</ul>
```
{{/markdown}}
  </div>
  <div class="large-6 columns">
    {{> examples_dropdown_directions}}
  </div>
</div>

***

Available class options:

* `tiny`: Make the dropdown have a max-width of 200px
* `small`: Make the dropdown have a max-width of 300px
* `medium`: Make the dropdown have a max-width of 500px
* `large`: Make the dropdown have a max-width of 800px
* `mega`: Make the dropdown go full 100% width
* `content`: Add padding inside the dropdown for better-looking content

##### Hoverable Dropdown Option

If you'd rather have your dropdown be accessible by hover, you can add a data-option to the target element:

<div class="row">
  <div class="large-6 columns">
    <h4>HTML</h4>
{{> examples_dropdown_hoverable_rendered}}
  </div>
  <div class="large-6 columns">
    <h4>Rendered HTML</h4>
{{> examples_dropdown_hoverable}}
  </div>
</div>

***

## Accessibility

<p class="panel">This component is not yet accessible. Stay tuned for updates in future releases.</p>

***

## Customize with Sass

Dropdowns can be easily customized using our Sass variables.

<h4>SCSS</h4>

{{> examples_dropdown_variables}}

***

## Semantic Markup With Sass

You can create your own dropdowns using our Sass mixins.

<h3>Basic</h3>

You can use the `dropdown-container()` and `dropdown-style()` mixins to create your own dropdowns, like so:

##### The Container Mixin

<h4>SCSS</h4>

{{#markdown}}
```scss
.custom-dropdown-container-class {
  @include dropdown-container();
}
```
{{/markdown}}

##### The List Style Mixin

<h4>SCSS</h4>

{{#markdown}}
```scss
.custom-dropdown-container-class {
  @include dropdown-container();

  li { @include dropdown-style; }
}
```
{{/markdown}}

<h3>Advanced</h3>

You can further customize your dropdowns with the options in the `dropdown-container()` mixin:

<h4>SCSS</h4>

{{#markdown}}
```scss
.custom-dropdown-container-class {
  @include dropdown-container(
    // Sets list-style. Default: list. Options: [list, content]
    $content:list,
    // Sets if dropdown has triangle. Default:true.
    $triangle:true,
    // Sets max-width. Default: $f-dropdown-max-width
    $max-width
  );

  li { @include dropdown-style; }
}
```
{{/markdown}}

***

## Configure With Javascript

It's easy to configure dropdowns using our provided Javascript. You can use data-attributes or plain old Javascript. Make sure `jquery.js`, `foundation.js` and `foundation.dropdown.js` have been included on your page before continuing. For example, add the following before the closing `<body>` tag:

{{#markdown}}
  ```html
<script src="js/vendor/jquery.js"></script>
<script src="js/foundation/foundation.js"></script>
<script src="js/foundation/foundation.dropdown.js"></script>
  ```
{{/markdown}}

### Optional Javascript Configuration

#### JS

{{#markdown}}
```js
$(document).foundation({
  dropdown: {
    // specify the class used for active dropdowns
    active_class: 'open'
  }
});
```
{{/markdown}}

***

### Sass Errors?

If the default "foundation" import was commented out, then make sure you import this file:

<h4>SCSS</h4>

```scss
@import "foundation/components/dropdown";
```