# Dropdown

Defines different styles for a toggleable dropdown.

## Usage

Any content, like a button, can toggle a dropdown. Just wrap the toggle with a `<div>` element and add the `data-uk-dropdown` attribute. Add the `.uk-dropdown` class to a child `<div>` element to create the dropdown itself. A dropdown can be enabled by either hovering or clicking the the toggle.

Data attribute | Description
--- | ---
`data-uk-dropdown` | Opens the dropdown on hover and adds a little delay, so the dropdown won't disappear immediately, once you stop hovering the toggle.
`data-uk-dropdown="{mode:'click'}"` | Opens the dropdown by clicking the toggle. The dropdown closes again on the next click.

IMPORTANT To apply a dropdown, it is important that a parent element has a relative position to align the dropdown properly. Many components create the position context by default, like the Button, Navbar, Subnav and the Tab component.

### Example

NOTE In this example we are using a button from the Button component as a toggle.

### Markup

    <!-- This is the container enabling the JavaScript -->
    <div data-uk-dropdown>

        <!-- This is the element toggling the dropdown -->
        <div>...</div>

        <!-- This is the dropdown -->
        <div class="uk-dropdown">...</div>

    </div>

    <!-- This is the container enabling the JavaScript in click mode -->
    <div data-uk-dropdown="{mode:'click'}">

        <!-- This is the element toggling the dropdown -->
        <div>...</div>

        <!-- This is the dropdown -->
        <div class="uk-dropdown">...</div>

    </div>

### Delayed dropdowns in hover mode

You can set a `delay` parameter in milliseconds to prevent the immediate appearance of the dropdown.

#### Markup

    <div class="uk-dropdown" data-uk-dropdown="{delay: 1000}">
        ...
    </div>

### Dropdown with navs

A dropdown can contain a nav from the Nav component. Just add the `.uk-nav` class and the `.uk-nav-dropdown` modifier to a `<ul>` element.

#### Markup

    <div class="uk-dropdown">
        <ul class="uk-nav uk-nav-dropdown">...</ul>
    </div>

## Alignment modifiers

To align the dropdown menu, just add the `pos:''` parameter to the data attribute.

Parameter | Description
--- | ---
`pos:'bottom-left'` | This is the default behavior. Left aligned dropdown below the toggle.
`pos:'bottom-center'` | Centered dropdown below the toggle.
`pos:'bottom-right'` | Right aligned dropdown below the toggle.
`pos:'top-left'` | Left aligned dropdown above the toggle.
`pos:'top-center'` | Centered dropdown above the toggle.
`pos:'top-right'` | Right aligned dropdown above the toggle.
`pos:'left-top'` | Top aligned dropdown left of the toggle.
`pos:'left-center'` | Centered dropdown left of the toggle.
`pos:'left-bottom'` | Bottom aligned dropdown left of the toggle.
`pos:'right-top'` | Top aligned dropdown right of the toggle.
`pos:'right-center'` | Centered dropdown right of the toggle.
`pos:'right-bottom'` | Bottom aligned dropdown right of the toggle.

### Example

### Markup

    <div data-uk-dropdown="{pos:'bottom-center'}"> ... </div>

    <div data-uk-dropdown="{pos:'top-right'}"> ... </div>

    <div data-uk-dropdown="{pos:'left-center'}"> ... </div>

    <div data-uk-dropdown="{pos:'right-top'}"> ... </div>

### Justify dropdown

To justify a dropdown, just add the `data-uk-dropdown="{justify:'#ID'}"` attribute. The parent element, to which the dropdown should be justified, needs to have the target id, so the dropdown will expand to the full width of the targeted element.

#### Example

#### Markup

    <!-- This is the parent element to which the dropdown is being justified -->
    <div id="my-id">

        <!-- This is the container enabling the JavaScript -->
        <div class="uk-button-dropdown" data-uk-dropdown="{justify:'#my-id'}">

            <!-- This is the element toggling the dropdown -->
            <button class="uk-button">...</button>

            <!-- This is the dropdown -->
            <div class="uk-dropdown">...</div>
        </div>
    </div>

### Automatic dropdown flip

By default, the dropdown flips automatically when it exceeds the viewport's edge. If you want to flip it according to a container's boundary, just add the `data-uk-dropdown="{boundary:'#ID'}"` attribute, using a selector for the container.

#### Example

#### Markup

    <div id="my-id">
        <div class="uk-button-dropdown" data-uk-dropdown="{boundary:'#my-id'}">...</div>
    </div>

## Grid

You can even place a grid from the Grid component inside a dropdown, which can hold a navigation or any other content. Just wrap the content with a `<div>` and add the `.uk-grid` class. To optimize the grid for use inside the dropdown, add the `.uk-dropdown-grid` class. Add one of the `.uk-dropdown-width-*` classes to the grid's child elements to multiply the dropdown's width by up to 5.

### Example

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt.
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt.
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt.
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt.

### Markup

    <div class="uk-dropdown uk-dropdown-width-2">

        <div class="uk-grid uk-dropdown-grid">
            <div class="uk-width-1-2">
                <ul class="uk-nav uk-nav-dropdown uk-panel">...</ul>
                <div class="uk-panel">...</div>
            </div>

            <div class="uk-width-1-2">
                <div class="uk-panel">...</div>
            </div>
        </div>

    </div>

### Responsive behavior

In narrower viewports, like phones, there might not be enough space for the dropdown to expand. In that case the dropdown flips its alignment. Should there still not be enough space, the grid columns take up full width and stack vertically inside the dropdown.

## Small modifier

By default, the dropdown has a fixed width and the text is wrapping into the next line. If you want your dropdown to be smaller, so that it extends to the width of its content without the text wrapping, add the `.uk-dropdown-small` class. This is useful for button dropdowns.

#### Example

#### Markup

    <div class="uk-dropdown uk-dropdown-small">...</div>

## Scrollable modifier

To give the dropdown a fixed height and enable its content to scroll, just add the `.uk-dropdown-scrollable` class.

### Example

### Markup

    <div class="uk-dropdown uk-dropdown-scrollable">...</div>

## Navbar modifier

Dropdowns are an essential part of a navbar from the Navbar component. Just add the `.uk-dropdown-navbar` class to the dropdown, so the dropdown fits perfectly into the navbar.

### Example

### Markup

    <nav class="uk-navbar">
        <ul class="uk-navbar-nav">

            <!-- This is the container enabling the JavaScript -->
            <li class="uk-parent" data-uk-dropdown>

                <!-- This is the menu item toggling the dropdown -->
                <a href="">...</a>

                <!-- This is the dropdown -->
                <div class="uk-dropdown uk-dropdown-navbar">
                    <ul class="uk-nav uk-nav-navbar">
                        <li><a href="">...</a></li>
                    </ul>
                </div>

            </li>
        </ul>
    </nav>

## Dropdown Blank

Sometimes you might want to have the functionality of the dropdown but not its styling. In that case just add the `.uk-dropdown-blank` class instead of `.uk-dropdown`.

### Example

### Title

Lorem ipsum dolor sit amet, consectetur adipisicing elit.

NOTE In this example we are using a panel from the Panel component to style the dropdown.

### Markup

     <div class="uk-dropdown-blank uk-panel uk-panel-box">...</div>

## Dropdown in buttons

A button from the Button component can be used to trigger a dropdown menu.

### Example

### Markup

    <!-- This is the container enabling the JavaScript -->
    <div class="uk-button-dropdown" data-uk-dropdown>

        <!-- This is the button toggling the dropdown -->
        <button class="uk-button">...</button>

        <!-- This is the dropdown -->
        <div class="uk-dropdown uk-dropdown-small">
            <ul class="uk-nav uk-nav-dropdown">
                <li><a href="">...</a></li>
                <li><a href="">...</a></li>
            </ul>
        </div>

    </div>

### Dropdown in button groups

Use button groups from the Button component to split buttons into a standard action and a dropdown toggle.

#### Example

#### Markup

    <div class="uk-button-group">

        <!-- This is a button -->
        <button class="uk-button">...</button>

        <!-- This is the container enabling the JavaScript -->
        <div data-uk-dropdown="{mode:'click'}">

            <!-- This is the button toggling the dropdown -->
            <a href="" class="uk-button">...</a>

            <!-- This is the dropdown -->
            <div class="uk-dropdown uk-dropdown-small">
                <ul class="uk-nav uk-nav-dropdown">
                    <li><a href="">...</a></li>
                    <li><a href="">...</a></li>
                </ul>
            </div>

        </div>
    </div>

## Dropdown in subnavs

Dropdowns can also be applied to a subnav from the Subnav component.

#### Example

#### Markup

    <ul class="uk-subnav uk-subnav-pill">
        <li><a href="">...</a></li>

        <!-- This is the container enabling the JavaScript -->
        <li data-uk-dropdown="{mode:'click'}">

            <!-- This is the nav item toggling the dropdown -->
            <a href="">...</a>

            <!-- This is the dropdown -->
            <div class="uk-dropdown uk-dropdown-small">
                <ul class="uk-nav uk-nav-dropdown">
                    <li><a href="">...</a></li>
                </ul>
            </div>

        </li>
    </ul>

## Dropdown in tabs

Dropdowns can be used on a tab from the Tab component.

#### Example

- Tab One
- Tab Two
- More

#### Markup

    <ul class="uk-tab" data-uk-tab>
        <li><a href="">...</a></li>

        <!-- This is the container enabling the JavaScript -->
        <li data-uk-dropdown="{mode:'click'}">

            <!-- This is the menu item toggling the dropdown -->
            <a href="">...</a>

            <!-- This is the dropdown -->
            <div class="uk-dropdown uk-dropdown-small">
                <ul class="uk-nav uk-nav-dropdown">
                    <li><a href="">...</a></li>
                </ul>
            </div>
        </li>
    </ul>

## JavaScript options

This is an example of how to set options via attribute:

    data-uk-dropdown="{mode:'hover'}"

Option | Possible value | Default | Description
--- | --- | --- | ---
`pos` | string | bottom-left | Dropdown position
`mode` | hover, click | hover | Dropdown trigger behaviour
`remaintime` | integer | 800 | Remain time before auto closing dropdown in hover mode
`justify` | CSS selector | false | Stretch dropdown width to a specified element
`boundary` | window | CSS selector | Referenced element to keep dropdowns visibilty
`delay` | integer | 0 | Delay time in hover mode before a dropdown is shown in ms
`hoverDelayIdle` | integer | 250 | Is added to the delay time when hovering from one active dropdown to another dropdown (in ms)
`preventflip` | mixed | false | Prevent automatic dropdown flip

### Events

You can bind callbacks to following events for custom functionality:

Name | Description
--- | ---
`show.uk.dropdown` | Triggered on dropdown show
`hide.uk.dropdown` | Triggered on dropdown hide
`stack.uk.dropdown` | Triggered when a dropdown stacks to fit into screen

### Example

    $('[data-uk-dropdown]').on('show.uk.dropdown', function(){
        // custom code...
    });

## CSS options

Add class `.uk-dropdown-close` to dropdown container or to item to hide dropdown when user click on item.