Figuration v4.4 is now available!

Dropdown dropdown.js

Add a context menu or list of links to a control item. Support for nested lists is included automatically.

Notices

Widget Dependencies

Dropdown requires the following:

  • The third-party library Popper to provide dynamic positioning and viewport detection. Static positioning does not require the use of Popper.js.

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.

From a usability perspective, the example where the currently displayed tab's trigger element might not immediately visible (as it could be inside a closed dropdown menu) would cause confusion. From an accessibility point of view, there is currently no sensible way to map this sort of construct to a standard WAI ARIA pattern, meaning that it cannot be easily made understandable to users of assistive technologies.

Overview

Wrap the dropdown's toggle (your button or link) and the dropdown menu within .dropdown, or another element that declares position: relative;. Dropdowns can be triggered from <a> or <button> elements.

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

There is an expand on hover option available, even though we recommend that you use the default click to toggle mode for consitent usability across devices.

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.

<div class="dropdown">
<a href="#" role="button" data-cfw="dropdown">
Toggle Dropdown
</a>
<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>
</ul>
</div>

Toggle Indicator

Optionally use the .caret utility icon and add it as an element within the control element. Use spacing utilities as needed.

We use this method instead of using a class placed on the control so that you can use your own icons as needed, and not have interference from hard-coded functionality.

<div class="dropdown">
<a href="#" role="button" data-cfw="dropdown">
Toggle Dropdown<span class="caret ms-0_25" aria-hidden="true"></span>
</a>
<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>
</ul>
</div>

Single Button Dropdown

You can also 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 btn-info btn-group-end" data-cfw="dropdown">
Dropdown <span class="caret" aria-hidden="true"></span>
</button>
<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>
</ul>
</div>

Split Button Dropdown

Similarly, create split button dropdowns with virtually the same markup as single button dropdowns, but with the addition of .btn-icon for proper spacing around the caret. We use this extra class to reduce the horizontal padding on either side of the caret and provide a more appropriately sized hit area next to the main button.

The use of the .btn-group-end class allows us to place the dropdown within the .btn-group itself and not reset the border-radius on the end side of the button.

<div class="btn-group">
<button type="button" class="btn btn-info">Default</button>
<button type="button" class="btn btn-info btn-icon btn-group-end" data-cfw="dropdown" aria-label="Toggle Dropdown">
<span class="caret" aria-hidden="true"></span>
</button>
<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>
</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 separate and nested .nav-item and .nav-link elements as in the following example.

<nav class="navbar navbar-expand navbar-light bg-light">
<a href="#" class="navbar-brand">Navbar</a>
<ul class="navbar-nav">
<li class="nav-item dropdown">
<a href="#" role="button" class="nav-link" data-cfw="dropdown">Dropdown<span class="caret ms-0_25" aria-hidden="true"></span></a>
<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>
</li>
</ul>
</nav>

Components

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

<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>

Add a non-interactive text item to a dropdown menu with .dropdown-text.

<ul class="dropdown-menu">
<li class="dropdown-text">Non-interactive text</li>
<li><a href="#">Action</a></li>
<li><a href="#">Another action</a></li>
</ul>

Separate groups of related menu items with a divider by using .dropdown-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 a item in the dropdown to make them visually appear disabled.

Disabling Anchors

Please refer to the Accessiblity notes about disabled anchors.

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

Active Menu Items

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

To convey the active state to assistive technologies, use the aria-current attribute — using the page value for the current page, or true for the current item in a set.

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

You can nest submenus by adding a nested list along side it's toggle.

<div class="dropdown">
<button type="button" class="btn btn-info" data-cfw="dropdown">
Dropdown <span class="caret" aria-hidden="true"></span>
</button>
<ul class="dropdown-menu">
<li class="dropdown-header">Sample Header</li>
<li><a href="#">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><a href="#">Another action</a></li>
</ul>
</div>

'Back' Menu Items

Using the backlink option, 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.

<div class="dropdown">
<button type="button" class="btn btn-info" data-cfw="dropdown" data-cfw-dropdown-backlink="true">
Dropdown <span class="caret" aria-hidden="true"></span>
</button>
<ul class="dropdown-menu">
<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>
</ul>
</li>
<li class="dropdown-divider"></li>
<li><a class="disabled">Disabled item</a></li>
</ul>
</div>

Special Items

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.

However, there is some support for handling <button>, <input>, and <textarea> elements within a menu. Each of these special items require the use of either the .dropdown-item or .dropdown-text class when inside the menu to adjust their layout .

Buttons

You can optionally use <button> elements in your dropdowns instead of just <a>s.

<div class="dropdown">
<button type="button" class="btn btn-info" data-cfw="dropdown" data-cfw-dropdown-backlink="true">
Dropdown <span class="caret" aria-hidden="true"></span>
</button>
<ul class="dropdown-menu">
<li><button type="button" class="dropdown-item">Regular button</button></li>
<li><button type="button" class="dropdown-item active">Active button</button></li>
<li><button type="button" class="dropdown-item">Another button</button></li>
<li class="dropdown-divider"></li>
<li><button type="button" class="dropdown-item" disabled>Disabled button</button></li>
</ul>
</div>

Checkbox and Radio Inputs

Checkbox and radio inputs are allowed, but only one per menu item.

<div class="dropdown">
<button type="button" class="btn btn-info" data-cfw="dropdown" data-cfw-dropdown-backlink="true">
Dropdown <span class="caret" aria-hidden="true"></span>
</button>
<ul class="dropdown-menu">
<li class="dropdown-text">
<div class="form-check">
<input type="checkbox" id="checkbox1" class="form-check-input">
<label for="checkbox1" class="form-check-label">Checkbox 1</label>
</div>
</li>
<li class="dropdown-text">
<div class="form-check">
<input type="checkbox" id="checkbox2" class="form-check-input">
<label for="checkbox2" class="form-check-label">Checkbox 2</label>
</div>
</li>
<li class="dropdown-text">
<div class="form-check">
<input type="checkbox" id="checkbox3" class="form-check-input">
<label for="checkbox3" class="form-check-label">Checkbox 3</label>
</div>
</li>
</ul>
</div>
<div class="dropdown">
<button type="button" class="btn btn-info" data-cfw="dropdown" data-cfw-dropdown-backlink="true">
Dropdown <span class="caret" aria-hidden="true"></span>
</button>
<ul class="dropdown-menu">
<li class="dropdown-text">
<div class="form-check">
<input type="radio" id="radio1" name="dropradio" class="form-check-input">
<label for="radio1" class="form-check-label">Radio 1</label>
</div>
</li>
<li class="dropdown-text">
<div class="form-check">
<input type="radio" id="radio2" name="dropradio" class="form-check-input">
<label for="radio2" class="form-check-label">Radio 2</label>
</div>
</li>
<li class="dropdown-text">
<div class="form-check">
<input type="radio" id="radio3" name="dropradio" class="form-check-input">
<label for="radio3" class="form-check-label">Radio 3</label>
</div>
</li>
</ul>
</div>

Textual Inputs

Add <input>, <textarea>, or <select> items to your dropdown menu. Other types of textual inputs have not been tested, and may cause issues. Again, use only one per menu item.

<div class="dropdown">
<button type="button" class="btn btn-info" data-cfw="dropdown" data-cfw-dropdown-backlink="true">
Dropdown <span class="caret" aria-hidden="true"></span>
</button>
<ul class="dropdown-menu">
<li><a href="#">Action</a></li>
<li><a href="#">Action</a></li>
<li>
<div class="dropdown-text">
<label for="input1" class="sr-only">Example input</label>
<input type="text" id="input1" class="form-control" placeholder="text input">
</div>
</li>
<li>
<div class="dropdown-text">
<label for="textarea1" class="sr-only">Example textarea</label>
<textarea id="textarea1" class="form-control" placeholder="textarea"></textarea>
</div>
</li>
<li>
<div class="dropdown-text">
<label for="select1" class="sr-only">Example select</label>
<select id="select1" class="form-control">
<option>One</option>
<option>Two</option>
<option>Three</option>
</select>
</div>
</li>
<li><a href="#">Action</a></li>
</ul>
</div>

Form

Put a form within a dropdown menu, or make it into a dropdown menu. Use spacing utilities to adjust layout as needed. However as mentioned earlier, using a Popover widget may be a more accessible alternative.

<div class="dropdown">
<button type="button" class="btn btn-info" data-cfw="dropdown">
Dropdown form
<span class="caret" aria-hidden="true"></span>
</button>
<ul class="dropdown-menu">
<li class="dropdown-text pb-1">
<form>
<div class="mb-0_5">
<label for="dropdownForm0" class="form-label">Email address</label>
<input type="email" class="form-control" id="dropdownForm0" placeholder="email@example.com">
</div>
<div class="mb-1">
<label for="dropdownForm1" class="form-label">Password</label>
<input type="password" class="form-control" id="dropdownForm1" placeholder="Password">
</div>
<div class="mb-1">
<div class="form-check form-checkradio">
<input type="checkbox" id="dropdownForm2" class="form-check-input">
<label for="dropdownForm2" class="form-check-label">Remember me</label>
</div>
</div>
<button type="submit" class="btn btn-primary">Sign in</button>
</form>
</li>
<li class="dropdown-divider"></li>
<li>
<a class="dropdown-item" href="#">New around here? Sign up</a>
</li>
<li>
<a class="dropdown-item" href="#">Forgot password?</a>
</li>
</ul>
</div>

Variants

Reverse Alignment

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

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

Heads up! When using the right-to-left, rtl, variant of Figuration all horizontal directions will be reversed. Meaning left becomes right, and vice-versa.

<div class="dropdown float-end">
<button type="button" class="btn btn-info" data-cfw="dropdown" data-cfw-dropdown-backlink="true">
Reverse Dropdown <span class="caret" aria-hidden="true"></span>
</button>
<ul class="dropdown-menu dropreverse">
<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="dropdown-divider"></li>
<li><a href="#">Separated link</a></li>
</ul>
</li>
<li class="dropdown-divider"></li>
<li><a class="disabled">Disabled link</a></li>
</ul>
</div>

Dropup

Trigger dropdown menus above elements by adding .dropup to the .dropdown-menu element. The visual caret for the toggle control can be reversed in direction by switching to .caretup.

<div class="dropdown">
<button type="button" class="btn btn-info" data-cfw="dropdown" data-cfw-dropdown-backlink="true">
Dropup <span class="caretup" aria-hidden="true"></span>
</button>
<ul class="dropdown-menu dropup">
...
</ul>
</div>

Side Aligned

Use .dropstart and .dropend to attach the menu to the side of the trigger. As indicated by the classnames, .dropstart attaches the submenu to the start side of the parent menu, while .dropend attaches on the end side. Simply place either class on the .dropdown-menu element. This can also be combined with .dropup.

Submenus will continue to open in the same direction as the parent, unless Submenu Alignment overrides are used.

<div class="btn-group">
<button type="button" class="btn btn-info btn-group-end" data-cfw="dropdown">
<span class="caret" aria-hidden="true"></span> Dropstart
</button>
<ul class="dropdown-menu dropstart">
...
</ul>
</div>

<div class="btn-group">
<button type="button" class="btn btn-info btn-group-end" data-cfw="dropdown">
Dropend <span class="caret" aria-hidden="true"></span>
</button>
<ul class="dropdown-menu dropend">
...
</ul>
</div>

<div class="btn-group">
<div class="btn-group">
<button type="button" class="btn btn-info" data-cfw="dropdown" aria-label="Toggle Dropdown">
<span class="caret" aria-hidden="true"></span>
</button>
<ul class="dropdown-menu">
...
</ul>
</div>
<button type="button" class="btn btn-info">Split Dropstart</button>
</div>

<div class="btn-group">
<button type="button" class="btn btn-info">Split Dropend</button>
<div class="btn-group">
<button type="button" class="btn btn-info" data-cfw="dropdown" aria-label="Toggle Dropdown">
<span class="caret" aria-hidden="true"></span>
</button>
<ul class="dropdown-menu">
...
</ul>
</div>
</div>

Center Aligned

Use .dropcenter to have the menu centered below the toggle control. Combine with .dropup to have the menu centered above the toggle control.

<div class="dropdown">
<button type="button" class="btn btn-info" data-cfw="dropdown">
Centered Dropdown <span class="caretup" aria-hidden="true"></span>
</button>
<ul class="dropdown-menu dropcenter">
...
</ul>
</div>

<div class="dropdown">
<button type="button" class="btn btn-info" data-cfw="dropdown">
Centered Dropup <span class="caretup" aria-hidden="true"></span>
</button>
<ul class="dropdown-menu dropup dropcenter">
...
</ul>
</div>

Middle Aligned

Use .dropmiddle to align the menu with the middle of the toggle control. The use .dropstart or .dropend is required in order to indicate which side of the toggle control to attach the menu.

<div class="dropdown">
<button type="button" class="btn btn-info" data-cfw="dropdown">
Start Middle Dropdown <span class="caretup" aria-hidden="true"></span>
</button>
<ul class="dropdown-menu dropstart dropmiddle">
...
</ul>
</div>

<div class="dropdown">
<button type="button" class="btn btn-info" data-cfw="dropdown">
End Middle Dropdown <span class="caretup" aria-hidden="true"></span>
</button>
<ul class="dropdown-menu dropend dropmiddle">
...
</ul>
</div>

You can also use the available .dropstart and .dropend to switch submenu directions if needed. Place either class on the ol or ul submenu list element.

<div class="dropdown">
<button type="button" class="btn btn-info" data-cfw="dropdown">
Dropdown <span class="caret" aria-hidden="true"></span>
</button>
<ul class="dropdown-menu">
<li class="dropdown-header">Dropdown header</li>
<li><a href="#">Action</a></li>
<li>
<a href="#">Start side menu</a>
<ul class="dropstart">
<li>
<a href="#">Start side menu</a>
<ul class="dropstart">
<li><a href="#">Action</a></li>
<li><a href="#">Another action</a></li>
</ul>
</li>
<li>
<a href="#">End side menu</a>
<ul class="dropend">
<li><a href="#">Action</a></li>
<li><a href="#">Another action</a></li>
</ul>
</li>
</ul>
</li>
<li>
<a href="#">End side menu</a>
<ul class="dropend">
<li>
<a href="#">Start side menu</a>
<ul class="dropstart">
<li><a href="#">Action</a></li>
<li><a href="#">Another action</a></li>
</ul>
</li>
<li>
<a href="#">End side menu</a>
<ul class="dropend">
<li><a href="#">Action</a></li>
<li><a href="#">Another action</a></li>
</ul>
</li>
</ul>
</li>
<li class="dropdown-divider"></li>
<li><a href="#">Separated link</a></li>
</ul>
</div>

Using a Reference

Use the reference option to help control the location of a dropdown menu.

<div class="d-flex">
<div class="btn-group me-1">
<button type="button" class="btn btn-info">Default</button>
<button type="button" class="btn btn-info btn-icon btn-group-end" data-cfw="dropdown" aria-label="Toggle Dropdown">
<span class="caret" aria-hidden="true"></span>
</button>
<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>
</ul>
</div>

<div class="btn-group">
<button type="button" class="btn btn-info">Reference</button>
<button type="button" class="btn btn-info btn-icon btn-group-end" data-cfw="dropdown" data-cfw-dropdown-reference="parent" aria-label="Toggle Dropdown">
<span class="caret" aria-hidden="true"></span>
</button>
<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>
</ul>
</div>
</div>

Auto Close

By default, the dropdown menu is closed when clicking inside or outside the dropdown menu. You can use the autoClose option to change this behavior of the dropdown.

When auto close is being used, pressing the ESC key will still close the menu (or submenu), and all methods should work as expected.

<div class="btn-group">
<button type="button" class="btn btn-info btn-group-end" data-cfw="dropdown" data-cfw-dropdown-auto-close="true">
Default close <span class="caret" aria-hidden="true"></span>
</button>
<ul class="dropdown-menu">
...
</ul>
</div>

<div class="btn-group">
<button type="button" class="btn btn-info btn-group-end" data-cfw="dropdown" data-cfw-dropdown-auto-close="false">
Manual close <span class="caret" aria-hidden="true"></span>
</button>
<ul class="dropdown-menu">
...
</ul>
</div>

<div class="btn-group">
<button type="button" class="btn btn-info btn-group-end" data-cfw="dropdown" data-cfw-dropdown-auto-close="outside">
Outside close <span class="caret" aria-hidden="true"></span>
</button>
<ul class="dropdown-menu">
...
</ul>
</div>
<div class="btn-group">
<button type="button" class="btn btn-info btn-group-end" data-cfw="dropdown" data-cfw-dropdown-auto-close="inside">
Inside close <span class="caret" aria-hidden="true"></span>
</button>
<ul class="dropdown-menu">
...
</ul>
</div>
</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 empty ($.noop) mouseover handlers to the immediate children of the <body> element. This ugly hack is necessary to work around a quirk in iOS' event delegation, which would otherwise prevent a tap anywhere outside of the dropdown from triggering the code that closes the dropdown. Once the dropdown is closed, these additional empty mouseover handlers are removed.

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" to the dropdown toggle element, and the widget will automatically link to the sibling .dropdown-menu list element.

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="#" role="button" data-cfw="dropdown">Dropdown trigger</a>
<ul class="dropdown-menu">
...
</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". Make sure to change the case type of the option name from camelCase to kebab-case when passing the options via data attributes. For example, instead of using data-cfw-dropdown-autoClose="false", use data-cfw-dropdown-auto-close="false".

Name Type Default Description
target string null Either the selector, 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.
container element | false false

Appends the dropdown menu to a specific element. Example: container: 'body'

Note: Figuration is still using Popper v1, due to legacy support of IE11, and there is a known issue regarding using a positioned container that was not resolved until Popper v2. For the time being, be sure to use containers that are not positioned.

reference string | element 'toggle'

Reference element of the dropdown menu. Accepts the values of 'toggle', 'parent', an HTMLElement reference, or an object providing getBoundingClientRect. For more information refer to Popper.js's referenceObject docs.

boundary string | element 'scrollParent'

Overflow constraint boundary of the dropdown menu. Accepts the values of 'viewport', 'window', 'scrollParent', or an HTMLElement reference (JavaScript only). For more information refer to Popper.js's preventOverflow docs.

flip boolean true

Allow Dropdown to flip in case of an overlapping on the reference element. For more information refer to Popper's flip docs.

display string 'dynamic'

By default, we use Popper for dynamic positioning. Disable this with 'static'.

popperConfig null | object null Pass a customized Popper configuration that will override the default Popper configuration.
autoClose boolean | string true

Configure the auto close behavior of the dropdown:

  • true - (default) the dropdown will close by clicking outside or inside the dropdown menu.
  • false - the dropdown will close by clicking the toggle button, but not when clicking inside or outside the menu.
  • 'inside' - the dropdown will close when clicking inside the dropdown menu.
  • 'outside' - the dropdown will close when clicking outside the dropdown menu.
loop boolean true Allow looping from the last menu item to the first menu item, and vice versa, when using arrow key navigation.
startEnd boolean true

When pressing the up arrow when focused on the main trigger, the last menu item in the list will recieve focus.

Note: Does not apply to submenus.
$('#myDropdown').CFW_Dropdown({
backlink: true
});

Methods

Event callbacks happen on the dropdown trigger element.

Method Name Description
toggle Toggles a root menu to be shown or hidden.
show Shows the root menu element.
hide Hides the root menu element, and any open submenus.
dispose Hides the root menu element and disconnect all the event listeners and data from the menu items and the trigger element.
$('#myDropdown').CFW_Dropdown('show');

Events

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

Show and hide, both before and after, events have an added relatedTarget property, whose value is the toggling anchor element.

Before and after hide events have a clickEvent property (only when the original event type is click) that contains an event object for the click event.

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...
});

Accessibility

General Purpose

While there are official ARIA Authoring Practices Guide menu button pattern and ARIA Authoring Practices Guide menu pattern specifications, they are mainly intended for application-style menus that invoke functionality or actions.

The dropdown widget provided by Figuration is intended be generic and apply to a wider number of use-cases. If you require full ARIA compliant menus, then you will need to add the appropriate role and aria- attributes as needed.

Keyboard Navigation

enter / space
When the focus is on the main trigger item, the menu is opened, and the menu items can be navigated using the arrow keys.
esc
Closes the currently focused menu, and moved focus to the main trigger.
/
Moves focus to the previous or next item in the menu list. If current focus is in a textarea, the text caret will move accordingly. If current focus is on a checkbox or radio input, moves focus to the previous or next item in the menu list.
Opens the submenu if one exists. If current focus is in a text input or textarea, the text caret will move accordingly.
Closes the currently focused submenu, and returns focus back to the triggering element. If current focus is in a text input or textarea, the text caret will move accordingly.

SASS Reference

Variables

The available Customization options, or Sass variables, that can be customized for the dropdown component.

Name Type Default Description
$enable-dropdown boolean true Enable the generation of the dropdown component classes. Smaller segements of the dropdown component classes can be disabled with the following $enable-* variables.
$enable-dropdown-header boolean true Enable the generation of the dropdown header class.
$enable-dropdown-text boolean true Enable the generation of the dropdown text class.
$enable-dropdown-divider boolean true Enable the generation of the dropdown divider class.
$enable-dropdown-dropup boolean true Enable the generation of the dropdown dropup classes.
$enable-dropdown-back boolean true Enable the generation of the dropdown 'back' caret indicator class.
$dropdown-min-width string 10rem Minimum width for dropdown menus.
$dropdown-padding-x string 0 Horizontal padding for dropdown menus.
$dropdown-padding-y string .3125rem Vertical padding for dropdown menus.
$dropdown-spacer string .125rem Top vertical spacing for dropdown menus.
$dropdown-font-size string $font-size-base Font size for dropdown menus.
$dropdown-line-height string $line-height-base Line height for dropdown menus.
$dropdown-bg string $component-bg Background color for dropdown menus.
$dropdown-border-color string $component-border-color Border color for dropdown menus.
$dropdown-border-width string $border-width Border width for dropdown menus.
$dropdown-border-radius string $border-radius Border radius for dropdown menus.
$dropdown-divider-width string $border-width Border width for dropdown menu dividers.
$dropdown-divider-color string $component-section-border-color Border color for dropdown menu dividers.
$dropdown-divider-spacer string .3125rem Vertical spacing for dropdown menu dividers.
$dropdown-divider-opacity string 1 Opacity for dropdown menu dividers.
$dropdown-box-shadow string map-get($shadows, "d2") Box shadow for dropdown menus.
$dropdown-link-color string $component-action-color Text color for dropdown menu links.
$dropdown-link-hover-color string $component-action-hover-color Text color for dropdown menu links in hover and focus states.
$dropdown-link-hover-bg string $component-hover-bg Background color for dropdown menu links in hover and focus states.
$dropdown-link-active-color string $component-active-color Text color for dropdown menu links in active state.
$dropdown-link-active-bg string $component-active-bg Background color for dropdown menu links in active state.
$dropdown-link-disabled-color string $component-active-color Text color for dropdown menu links in disabled state.
$dropdown-link-disabled-bg string $component-active-bg Background color for dropdown menu links in disabled state.
$dropdown-item-padding-y string .125rem Vertical padding for dropdown menu links.
$dropdown-item-padding-x string 1.125rem Horizontal padding for dropdown menu links.
$dropdown-header-padding string $dropdown-item-padding-y $dropdown-item-padding-x Padding for dropdown menu headers.
$dropdown-header-font-size string ($font-size-base * .875) Font size for dropdown menu headers.
$dropdown-header-font-weight string $font-weight-bold Font weight for dropdown menu headers.
$dropdown-header-color string $uibase-500 Text color for dropdown menu headers.
$dropdown-text-color string $body-color Text color for dropdown menu text.
$dropdown-caret-width string $caret-border-width Border width for dropdown submenu indicator.
$dropdown-caret-color string $uibase-400 Border color for dropdown submenu indicator.
$dropdown-caret-active-color string $component-active-color Border color for dropdown submenu indicator in active state.
$dropdown-caret-spacer-y string calc(#{$dropdown-line-height} * #{$dropdown-font-size} * .5) Top offset for dropdown submenu indicator.
$dropdown-caret-spacer-x string .375rem Horizontal offset for dropdown submenu indicator.
$dropdown-back-width string $caret-border-width Border width for dropdown menu 'back' indicator.
$back-caret-color string $uibase-400 Border color for dropdown menu 'back' indicator.
$dropdown-back-spacer-y string calc(#{$dropdown-line-height} * #{$dropdown-font-size} * .5) Top offset for dropdown menu 'back' indicator.
$dropdown-back-spacer-x string .375rem Horizontal offset for dropdown menu 'back' indicator.

Mixins

No mixins available.