Skip to main content
Figuration v3 Preview Available!
Widgets

Bring interactivity to your site with a selection of jQuery widgets (plugins) all built with accessibility and usability in mind.

Dropdown dropdown.js

Add dropdown menus to nearly anything with this widget, including buttons, navbars, tabs, and pills.

Incompatible Widgets

For accessibility reasons, do not mix use of the Tab widget and Dropdown widget in the same nav item. This will cause navigation and usability issues. One or the other, but not both.

Contents

Overview

The Dropdown widget in Figuration is primarily designed for menus and navigation. Not a container for forms or editable content, such as a login or registration. You might want to consider using the Popover widget instead, or reworking the workflow or interface design.

Examples

Here is a static example showing the dropdown layout and content pieces.

Basic Dropdown

Wrap the dropdown’s trigger and the dropdown menu within .dropdown, or another element that declares position: relative;. Then, add the menu’s HTML.

Because of the support for nested dropdown menus, it is currently required to use a ul element to build your dropdown menus.

<div class="dropdown">
  <a href="#" role="button" class="dropdown-toggle" data-cfw="dropdown" data-cfw-dropdown-toggle="#dropdownMenu1">
    Dropdown
  </a>
  <ul class="dropdown-menu" id="dropdownMenu1">
    <li><a href="#">Action</a></li>
    <li><a href="#">Another action</a></li>
    <li><a href="#">Something else here</a></li>
  </ul>
</div>

Single Button Dropdown

You can optionally use <button> elements in your dropdowns instead of <a>s. You can also use swap out the .dropdown class on the parent container with .btn-group if desired.

<div class="btn-group">
  <button type="button" class="btn dropdown-toggle" data-cfw="dropdown" data-cfw-dropdown-toggle="#dropdownMenu2">
    Dropdown
  </button>
  <ul class="dropdown-menu" id="dropdownMenu2">
    <li><a href="#">Action</a></li>
    <li><a href="#">Another action</a></li>
    <li><a href="#">Something else here</a></li>
  </ul>
</div>

Split Button Dropdown

Similarly, create split button dropdowns with virtually the same markup as single button dropdowns, but with the addition of .dropdown-toggle-split for proper spacing around the dropdown caret.

We use this extra class to reduce the horizontal padding on either side of the caret by 25% and remove the margin-left that’s added for regular button dropdowns. Those extra changes keep the caret centered in the split button and provide a more appropriately sized hit area next to the main button.

<div class="btn-group">
  <button type="button" class="btn">Default</button>
  <button type="button" class="btn dropdown-toggle dropdown-toggle-split" data-cfw="dropdown" data-cfw-dropdown-toggle="#dropdownMenu3">
    <span class="sr-only">Toggle Dropdown</span>
  </button>
  <ul class="dropdown-menu" id="dropdownMenu3">
    <li><a href="#">Action</a></li>
    <li><a href="#">Another action</a></li>
    <li><a href="#">Something else here</a></li>
  </ul>
</div>

Within a Navbar

Dropdowns also work in a navbar, but require the use of a wrapping element for positioning. Make sure to use seperate and nested .nav-item and .nav-link elements as in the following example.

<nav class="navbar navbar-light bg-faded">
    <a href="#" class="navbar-brand">Navbar</a>
    <ul class="nav navbar-nav">
        <li class="nav-item dropdown">
            <a href="#" class="nav-link dropdown-toggle" data-cfw="dropdown" data-cfw-dropdown-toggle="dropdownNav1">Dropdown</a>
            <ul class="dropdown-menu" data-cfw-dropdown-target="dropdownNav1">
                <li><a href="#">Action</a></li>
                <li><a href="#">Another action</a></li>
                <li><a href="#">Something else here</a></li>
                <li class="divider"></li>
                <li><a href="#">Separated link</a></li>
            </ul>
        </li>
    </ul>
</nav>

Components

Add a header to label sections of actions in any dropdown menu.

<ul class="dropdown-menu">
  <li class="dropdown-header">Dropdown header</li>
  <li><a href="#">Action</a></li>
  <li><a href="#">Another action</a></li>
</ul>

<ul class="dropdown-menu">
  <li><h6 class="dropdown-header">Dropdown header</h6></li>
  <li><a href="#">Action</a></li>
  <li><a href="#">Another action</a></li>
</ul>

Separate groups of related menu items with a divider.

<ul class="dropdown-menu">
  <li><a href="#">Action</a></li>
  <li><a href="#">Another action</a></li>
  <li><a href="#">Something else here</a></li>
  <li class="dropdown-divider"></li>
  <li><a href="#">Separated link</a></li>
</ul>

Disabled Menu Items

Add .disabled to the li item in the dropdown to style them as disabled.

<ul class="dropdown-menu">
  <li><a href="#">Regular link</a></li>
  <li class="disabled"><a href="#">Disabled link</a></li>
  <li><a href="#">Another link</a></li>
</ul>

The .disabled class uses pointer-events: none to try to disable the link functionality of <a>s, but that CSS property is not yet standardized. In addition, even in browsers that do support pointer-events: none, keyboard navigation remains unaffected, meaning that sighted keyboard users and users of assistive technologies will still be able to activate these links. So to be safe, add a tabindex="-1" attribute on these links (to prevent them from receiving keyboard focus) and use custom JavaScript to disable their functionality.

Active Menu Items

Add .active to the li item in the dropdown to show a visual emphasis.

<ul class="dropdown-menu">
  <li><a href="#">Regular link</a></li>
  <li class="active"><a href="#">Active link</a></li>
  <li><a href="#">Another link</a></li>
</ul>

‘Back’ Menu Items

Using the dropdown widget options you can have ‘back’ menu items automatically inserted into all submenus. These links will close the current submenu and move focus back onto the parent menu item. This can be useful if the parent menu/submenu item is being hidden, or obscured by the current submenu.

See the menu alignment section for an example of injected ‘back’ menu items.

Variants

Dropup

Trigger dropdown menus above elements by adding .dropup to the parent element. A .caret or .dropdown-toggle will reverse direction automatically.

<div class="dropdown dropup">
  <button type="button" class="btn dropdown-toggle" data-cfw="dropdown" data-cfw-dropdown-toggle="#dropdownVar1">
    Dropup
  </button>
  <ul class="dropdown-menu" id="dropdownVar1">
    <li><a href="#">Action</a></li>
    <li><a href="#">Another action</a></li>
    <li><a href="#">Something else here</a></li>
  </ul>
</div>

<div class="btn-group dropup">
  <button type="button" class="btn">Split Dropup</button>
  <button type="button" class="btn dropdown-toggle dropdown-toggle-split" data-cfw="dropdown" data-cfw-dropdown-toggle="#dropdownVar2">
    <span class="sr-only">Toggle Dropdown</span>
  </button>
  <ul class="dropdown-menu" id="dropdownVar2">
    <li><a href="#">Action</a></li>
    <li><a href="#">Another action</a></li>
    <li><a href="#">Something else here</a></li>
  </ul>
</div>

By default, a dropdown menu is automatically positioned 100% from the top and along the left side of its parent. While submenu items are aligned 100% to the left and to the top of its parent.

Add .dropdown-menu-left to a .dropdown-menu to right align the dropdown menu, this will also make all submenus open to the left side. This can also be combined with .dropup.

<div class="btn-group dropdown-menu-left" style="float: right;">
    <button type="button" class="btn btn-primary dropdown-toggle" data-cfw="dropdown" data-cfw-dropdown-toggle="dropdownVar3" data-cfw-dropdown-backlink="true">
        Drop Left
    </button>
    <ul data-cfw-dropdown-target="dropdownVar3">
        <li class="dropdown-header">Dropdown header</li>
        <li><a href="#">Action</a></li>
        <li><a href="#">Another action</a></li>
        <li>
           <a href="#">Something else here</a>
            <ul>
                <li><a href="#">Action</a></li>
                <li><a href="#">Another action</a></li>
                <li>
                    <a href="#">Something else here</a>
                    <ul>
                        <li><a href="#">Action</a></li>
                        <li><a href="#">Another action</a></li>
                    </ul>
                </li>
                <li class="divider"></li>
                <li><a href="#">Separated link</a></li>
            </ul>
        </li>
        <li class="divider"></li>
        <li class="disabled"><a href="#">Disabled link</a></li>
    </ul>
</div>

The menu alignment class of .dropdown-menu-left will also work with submenu items, and you can use the available .dropdown-menu-right to switch submenu directions if needed. Simply place either class on the li parent of the submenu list.

<div class="btn-group">
    <button type="button" class="btn dropdown-toggle" data-cfw="dropdown" data-cfw-dropdown-toggle="dropdownSub1" data-cfw-dropdown-backlink="true">
        Dropdown
    </button>
    <ul data-cfw-dropdown-target="dropdownSub1">
        <li class="dropdown-header">Dropdown header</li>
        <li><a href="#">Action</a></li>
        <li class="dropdown-menu-left">
            <a href="#">Left menu</a>
            <ul>
                <li class="dropdown-menu-left">
                    <a href="#">Left menu</a>
                    <ul>
                        <li><a href="#">Action</a></li>
                        <li><a href="#">Another action</a></li>
                    </ul>
                </li>
                <li class="dropdown-menu-right">
                    <a href="#">Right menu</a>
                    <ul>
                        <li><a href="#">Action</a></li>
                        <li><a href="#">Another action</a></li>
                    </ul>
                </li>
            </ul>
        </li>
        <li class="dropdown-menu-right">
            <a href="#">Right menu</a>
            <ul>
                <li class="dropdown-menu-left">
                    <a href="#">Left menu</a>
                    <ul>
                        <li><a href="#">Action</a></li>
                        <li><a href="#">Another action</a></li>
                    </ul>
                </li>
                <li class="dropdown-menu-right">
                    <a href="#">Right menu</a>
                    <ul>
                        <li><a href="#">Action</a></li>
                        <li><a href="#">Another action</a></li>
                    </ul>
                </li>
            </ul>
        </li>
        <li class="divider"></li>
        <li class="disabled"><a href="#">Separated link</a></li>
    </ul>
</div>

Usage

Via data attributes or JavaScript, the dropdown widget toggles hidden content (dropdown menus) by toggling the .open class on the parent list item.

On touch capable devices, the optional expand on hover functionality is forced off in favor of the default click interaction. Also, opening a dropdown adds a .dropdown-backdrop as a tap area for closing dropdown menus when tapping outside the menu, a requirement for proper iOS support. This means that switching from an open dropdown menu to a different dropdown menu requires an extra tap on mobile.

Note: The data-cfw="dropdown" attribute is relied on for closing dropdown menus at an application level, so it’s a good idea to always use it.

Via Data Attributes

Add data-cfw="dropdown" and a data-cfw-dropdown-toggle with a selector (jQuery style) or string value to then element to automatically assign control of a dropdown element. If using a string value, then assign a data-cfw-dropdown-target attribute, with a matching value to the element to apply the collapse to. Be sure to add the class dropdown-menu to the dropdown menu to ensure there is no flash of content at page load.

<div class="dropdown">
  <a href="#" data-cfw="dropdown" data-cfw-dropdown-toggle="dropdownExample">Dropdown trigger</a>
  <ul class="dropdown-menu" data-cfw-dropdown-target="dropdownExample">
    ...
  </ul>
</div>

Via JavaScript

Call the dropdowns via JavaScript:

$('#myDropdown').CFW_Dropdown();

Options

Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-cfw-dropdown, as in data-cfw-dropdown-backlink="true".

Name Type Default Description
toggle string null Either the selector (jQuery style), or the string related to the target dropdown having a data-cfw-dropdown-target attribute.
delay integer 350 Delay for hiding menu on loss of focus or hover when not in click only mode (milliseconds).
hover boolean false If hover style navigation should be enabled in addition to click/key navigation. If a touch capable device is found, this setting is overruled.
backlink boolean false Insert back links into submenus.
backtop boolean false If back links should be applied at the top level menu as opposed to only submenus.
backtext string Back Text to be used for back links.

Methods

.CFW_Dropdown(options)

Activates the dropdown menu. Accepts an optional options object.

$('#myDropdown').CFW_Dropdown({
    backlink: true
});

.CFW_Dropdown('toggle')

Toggles a root menu to be shown or hidden.

.CFW_Dropdown('show')

Shows the root menu element.

.CFW_Dropdown('hide')

Hides the root menu element.

Events

Event callbacks for the root menu happen on the toggle element. Callbacks for the submenus occur on the submenu’s sibling anchor (toggle).

Event Type Description
init.cfw.dropdown This event fires after the menu item is initialized.
beforeShow.cfw.dropdown This event is fired immediately when the internal showMenu method is called.
afterShow.cfw.dropdown This event is fired when a menu element has been made visible to the user.
beforeHide.cfw.dropdown This event is fired immediately when the internal hideMenu method is called.
afterHide.cfw.dropdown This event is fired when a menu element has been hidden from the user.

$('#mDropdown').on('afterHide.cfw.dropdown', function () {
  // do something...
});