Dropdowns

Dropdowns are toggleable lists of grouped options, specifically designed to overcome the native select element limitations.

When dropdowns are used on mobile devices, they do not trigger the native select UI, but instead, a list of options is toggled as an overlay. Keep in mind that dropdown elements cannot be focused on when using next/previous form helper buttons found in mobile device virtual keyboards when filling in forms.

Choosing between a dropdown component or a native select element is a compromise of functionality in either case - each element limitations should be examined per occasion before selecting the most appropriate of the two.

• Dropdown component
  • Persistent dropdown
• Dropdown nesting
• Dropdown global styling
• Multi-select dropdown
  • Multi-select dropdown with close button
• Form control dropdown variation
• Responsive inline dropdown menu
• Responsive masked dropdown
• Usage
  • Via data attributes
  • Via javascript
  • Javascript methods
  • Javascript events

Dropdown component

A dropdown at its simplest form is a container with a dropdown class that includes the dropdown trigger button that is defined by applyng the class btn-dropdown-toggle in a button, and a list of linkable items contained inside an ul. The result is displayed below.

Code output

HTML Markup

Copy<div class="dropdown">
  <button class="btn btn-main btn-dropdown-toggle" data-toggle="dropdown">Dropdown</button>
  <ul class="dropdown-menu">
    <li><a href=#>Option 1</a></li>
    <li><a href=#>Option 2</a></li>
    <li><a href=#>Option 3</a></li>
    <li><a href=#>Option 4</a></li>
    <li><a href=#>Option 5</a></li>
  </ul>
</div>

Persistent dropdown

By default, when clicking outside of an open dropdown element, the dropdown automatically closes. Adding a class dropdown-persisent on the dropdown component prevents this default behavior and leaves the specified dropdown opened. The persistent dropdown menu can only be closed by the dropdown trigger button.

Code output

HTML Markup

Copy<div class="dropdown dropdown-persistent">
  <button class="btn btn-main btn-dropdown-toggle" data-toggle="dropdown">Dropdown</button>
  <ul class="dropdown-menu">
    <li><a href=#>Option 1</a></li>
    <li><a href=#>Option 2</a></li>
    <li><a href=#>Option 3</a></li>
    <li><a href=#>Option 4</a></li>
    <li><a href=#>Option 5</a></li>
  </ul>
</div>

Dropdown nesting

One level of nesting is allowed in a dropdown component using the following markup.

Code output

HTML Markup

Copy<div class="dropdown">
  <button class="btn btn-main btn-dropdown-toggle" data-toggle="dropdown">Dropdown</button>
  <ul class="dropdown-menu">
    <li><a href=#>Option 1</a></li>
    <li><a href=#>Option 2</a></li>
    <li><span>Option 3</span>
      <ul>
        <li><a href=#>Nested option 1</a></li>
        <li><a href=#>Nested option 2</a></li>
        <li><a href=#>Nested option 3</a></li>
      </ul>
    </li>
    <li><a href=#>Option 4</a></li>
    <li><a href=#>Option 5</a></li>
  </ul>
</div>

Dropdown global styling

The dropdown is a versatile element that can be styled in various ways.

Contained dropdown menu

By adding the class dropdown-contained alongside the dropdown-menu, the dropdown menu height can be contained to a maximum height, after which the menu becomes scrollable.

Code output

HTML Markup

Copy<div class="dropdown">
  <button class="btn btn-main btn-dropdown-toggle" data-toggle="dropdown">Dropdown</button>
  <ul class="dropdown-menu dropdown-contained">
    <li><a href=#>Option 1</a></li>
    <li><a href=#>Option 2</a></li>
    <li><a href=#>Option 3</a></li>
    <li><a href=#>Option 4</a></li>
    <li><a href=#>Option 5</a></li>
    <li><a href=#>Option 6</a></li>
    <li><a href=#>Option 7</a></li>
    <li><a href=#>Option 8</a></li>
    <li><a href=#>Option 9</a></li>
    <li><a href=#>Option 10</a></li>
  </ul>
</div>

Dropdown toggle button styling

Since the trigger button is a simple button element, all button styles and sizing properties, defined in the buttons section of this framework can be applied on the dropdown toggle button, like in the following examples.

Code output

HTML Markup

Copy<div class="dropdown">
  <button class="btn btn-main btn-lg btn-dropdown-toggle" data-toggle="dropdown">Dropdown</button>
  <ul class="dropdown-menu">
    <li><a href=#>Option 1</a></li>
    <li><a href=#>Option 2</a></li>
    <li><a href=#>Option 3</a></li>
    <li><a href=#>Option 4</a></li>
    <li><a href=#>Option 5</a></li>
  </ul>
</div>

Dropdown menu alignment

By default, the dropdown menu is left aligned, but its alignnment can be adjusted using the appropriate classes dropdown-right or dropdown-center alongside the dropdown-menu class.

Code output

HTML Markup

Copy<div class="dropdown">
  <button class="btn btn-main btn-dropdown-toggle" data-toggle="dropdown">Dropdown center</button>
  <ul class="dropdown-menu dropdown-center">
    <li><a href=#>Option 1</a></li>
    <li><a href=#>Option 2</a></li>
    <li><a href=#>Option 3</a></li>
    <li><a href=#>Option 4</a></li>
    <li><a href=#>Option 5</a></li>
  </ul>
</div>

<div class="dropdown">
  <button class="btn btn-main btn-dropdown-toggle" data-toggle="dropdown">Dropdown right</button>
  <ul class="dropdown-menu dropdown-right">
    <li><a href=#>Option 1</a></li>
    <li><a href=#>Option 2</a></li>
    <li><a href=#>Option 3</a></li>
    <li><a href=#>Option 4</a></li>
    <li><a href=#>Option 5</a></li>
  </ul>
</div>

Full width dropdown menu

There are cases where the dropdown needs to fill all its parent container width; this can simply be achieved by applying the class dropdown-block on the dropdown component.

Code output

HTML Markup

Copy<div class="dropdown dropdown-block">
  <button class="btn btn-main btn-dropdown-toggle" data-toggle="dropdown">Dropdown</button>
  <ul class="dropdown-menu">
    <li><a href=#>Option 1</a></li>
    <li><a href=#>Option 2</a></li>
    <li><a href=#>Option 3</a></li>
    <li><a href=#>Option 4</a></li>
    <li><a href=#>Option 5</a></li>
  </ul>
</div>

Multi-select dropdown

The multi-select dropdown has been defined to overcome the limitations of the native select element when multiple options are required.

Code output

HTML Markup

Copy<div class="dropdown">
  <button class="btn btn-main btn-dropdown-toggle" data-toggle="dropdown">Dropdown</button>
  <ul class="dropdown-menu">
    <...>
    <li>
      <label class="custom-checkbox">
        <input value="checkbox1" type="checkbox">
        <span>List option 1</span>
      </label>
    </li>
    <...>
  </ul>
</div>

Multi-select dropdown with close button

By default, when clicking outside of an open multi-select dropdown component, the component automatically closes. If a close button is required, the dropdown menu has to be wrapped inside a dropdown-menu-wrap container, and the button has to be placed alongisde the dropdown-menu as a sibling, wrapped in its own dropdown-footer container as shown in the markup below.

Code output

HTML Markup

Copy<div class="dropdown dropdown-persistent">
  <button class="btn btn-main btn-dropdown-toggle" data-toggle="dropdown">Dropdown</button>
  <div class="dropdown-menu-wrap">
    <ul class="dropdown-menu">
      <li>
        <label class="custom-checkbox">
        <input type="checkbox" value="checkbox1">
        <span>List option 1</span>
        </label>
      </li>
      <...>
    </ul>
    <div class="dropdown-footer">
      <button class="btn btn-sm btn-main btn-dropdown-close">Done</button>
    </div>
  </div>
</div>

Form control dropdown variation

Due to the select element limitations, it is often required for the dropdown to be implemented inside forms. In order for the form to adapt to the form styling, a class dropdown-form-control has to be applied on the dropdown component, which essentially is a combination of styling the trigger button in a way that resembles a form control select element.

Despite the resemblence of a collapsed form control dropdown with the native select element, dropdowns allow for HTML rich styling compared to the limited option tags.

In the form control dropdown variation, the dropdown can be toggled either using a button or an input element - that also holds the value of the selected item. Keep in mind that a readonly attribute must be applied on the input for the component to function properly.

Code output

HTML Markup

Copy<div class="dropdown dropdown-form-control">
  <button class="btn-dropdown-toggle" data-toggle="dropdown">Form control dropdown with button toggle</button>
  <ul class="dropdown-menu">
    <li><a href=#>Option 1</a></li>
    <li><a href=#>Option 2</a></li>
    <li><a href=#>Option 3</a></li>
    <li><a href=#>Option 4</a></li>
    <li><a href=#>Option 5</a></li>
  </ul>
</div>

Copy<div class="dropdown dropdown-form-control">
  <input class="btn btn-dropdown-toggle" data-toggle="dropdown" value="Form control dropdown with input toggle" readonly>
  <ul class="dropdown-menu">
    <li><a href=#>Option 1</a></li>
    <li><a href=#>Option 2</a></li>
    <li><a href=#>Option 3</a></li>
    <li><a href=#>Option 4</a></li>
    <li><a href=#>Option 5</a></li>
  </ul>
</div>

Different size classes are available for the form control dropdown variation by applying a class form-control-{affix}, where affix can be either lg, sm or xs. The class names are semantic, are irrelevant to the responsive resolution tiers and override any button size classes contained within the dropdown component.

Code output

HTML Markup

Copy<div class="dropdown dropdown-form-control form-control-lg">
  <input class="btn-dropdown-toggle" data-toggle="dropdown" value="Large form control dropdown" readonly>
   <ul class="dropdown-menu">
      <li><a href=#>Option 1</a></li>
        <...>
      <li><a href=#>Option 5</a></li>
   </ul>
</div>

<div class="dropdown dropdown-form-control">
  <input class="btn-dropdown-toggle" data-toggle="dropdown" value="Normal form control dropdown" readonly>
  <ul class="dropdown-menu">
    <li><a href=#>Option 1</a></li>
      <...>
    <li><a href=#>Option 5</a></li>
  </ul>
</div>

<div class="dropdown dropdown-form-control form-control-sm">
  <input class="btn-dropdown-toggle" data-toggle="dropdown" value="Small form control dropdown" readonly>
  <ul class="dropdown-menu">
    <li><a href=#>Option 1</a></li>
      <...>
    <li><a href=#>Option 5</a></li>
  </ul>
</div>

<div class="dropdown dropdown-form-control form-control-xs">
  <input class="btn-dropdown-toggle" data-toggle="dropdown" value="Extra small form control dropdown" readonly>
  <ul class="dropdown-menu">
    <li><a href=#>Option 1</a></li>
      <...>
    <li><a href=#>Option 5</a></li>
  </ul>
</div>

The form control dropdown can also accept contextual validation classes like any other form control. Along with the static styling, hover and focus styling change accordingly.

Code output

HTML Markup

Copy<div class="dropdown dropdown-form-control form-control-success">
  <input class="btn-dropdown-toggle" data-toggle="dropdown" value="Form control dropdown at success state">
   <ul class="dropdown-menu">
      <li><a href=#>Option 1</a></li>
        <...>
      <li><a href=#>Option 5</a></li>
   </ul>
</div>

<div class="dropdown dropdown-form-control form-control-error">
  <input class="btn-dropdown-toggle" data-toggle="dropdown" value="Form control dropdown at error state">
   <ul class="dropdown-menu">
      <li><a href=#>Option 1</a></li>
        <...>
      <li><a href=#>Option 5</a></li>
   </ul>
</div>

Responsive inline dropdown menu

A dropdown-menu can be toggled inline instead of being an overlay, pushing all content below it, at the two extra small resolution tiers from 767px and below by applying a class dropdown-{affix}-inline where affix can be either xs or xxs. This feature is reserved only for small mobile devices, where it feels more natural compared to the default overlay dropdown menu functionality, while it feels awkward at larger screen resolution tiers.

It is recommended to use this feature only when the dropdown menu contains up to 10 list items to provide the best user experience - once a dropdown menu is toggled open, users should be able to scroll past it with one flick.

In the example below, the dropdown menu is toggled inline at the extra small resolution tier, up to 544px.

Code output

HTML Markup

Copy<div class="dropdown dropdown-xxs-inline">
  <button class="btn btn-simple btn-dropdown-toggle" data-toggle="dropdown">Dropdown</button>
   <ul class="dropdown-menu">
      <li><a href=#>Option 1</a></li>
      <li><a href=#>Option 2</a></li>
      <li><a href=#>Option 3</a></li>
      <li><a href=#>Option 4</a></li>
      <li><a href=#>Option 5</a></li>
      <li><a href=#>Option 6</a></li>
      <li><a href=#>Option 7</a></li>
      <li><a href=#>Option 8</a></li>
      <li><a href=#>Option 9</a></li>
      <li><a href=#>Option 10</a></li>
   </ul>
</div>

Responsive masked dropdown

In some cases, it might be required for some content to be constantly visible at a specific screen resolution tier, while being toggled on-demand at other resolution tiers, like long content of secondary importance or long lists of items like the ones found in appendices.

For this purpose a variation of the dropdown element has been developed, that allows any kind of content - not just unordered lists - to be toggleable at specific resolution tiers, while being constantly visible at other resolution tiers without any indication that the content is wrapped within a dropdown element.

The responsive masked dropdown classes are defined as dropdown-{affix}-masked where affix is one of the 6 responsive tier affixes xxs, xs, sm, md, lg, xl. on the specified resolution tier the dropdown content will be constantly visible as if it wasn't wrapped inside a dropdown component at all. The responsive masked dropdown classes can be combined to show content at more than one resolution tiers. Applying a responsive masked dropdown class changes the display of a dropdown component to block.

Some changes in the markup are required for this feature to work as shown below; the unordered list with class dropdown-menu is replaced with a div element that has the class dropdown-content applied. In the following example, the dropdown component is masked at the medium and large screen resolution tiers, while the default dropdown functionality is restored at smaller resolution tiers.

Code output

HTML Markup

Copy<div class="box pad-md">
  <div class="dropdown dropdown-md-masked dropdown-lg-masked">
  <button class="btn btn-main btn-dropdown-toggle" data-toggle="dropdown">Dropdown</button>
   <div class="dropdown-content pad-sm">
      <div class="list-group">
        <h6 class="list-header">List header</h6>
        <ul class="list-filters">
          <li><a href="#">List-item 1</a></li>
          <li><a href="#" class="active">List-item 2</a></li>
          <li><a href="#">List-item 3</a></li>
          <li><a href="#">List-item 4</a></li>
          <li><a href="#">List-item 5</a></li>
        </ul>
      </div>
    </div>
   </div>
</div>

Usage

Dropdown functionality can be enabled and controlled using HTML data attributes or Javascript.

Via data attributes

Dropdown functionality can be enabled by adding a data-toggle="dropdown" attribute on the btn-dropdown-toggle button of a dropdown component.

HTML Markup

Copy<div class="dropdown">
  <button class="btn btn-main btn-dropdown-toggle" data-toggle="dropdown">Dropdown</button>
  <ul class="dropdown-menu">
    <li><a href=#>Option 1</a></li>
    <li><a href=#>Option 2</a></li>
    <li><a href=#>Option 3</a></li>
    <li><a href=#>Option 4</a></li>
    <li><a href=#>Option 5</a></li>
  </ul>
</div>

Via Javascript

Dropdowns that hold a unique id can be called using Javascript.

Copy$('#id').dropdown()

Javascript methods

The following methods are available for dropdown components that hold a unique id.

Copy$('#id').dropdown('toggle')

Copy$('#id').dropdown('show')

Copy$('#id').dropdown('hide')

Javascript events

The dropdown component exposes events at specific triggering points to extend component functionality. Each event instance fires as soon as the pre-specified hooks are reached within the Javascript code. The following events are available for the dropdown component and are linked directly to the dropdown and not the control triggering elements, like the buttons triggering the dropdown.

Copy$('#id').on('shown.sky.dropdown', function(e) {
  // Extend function
});

Copy$('#id').on('hidden.sky.dropdown', function(e) {
  // Extend function
});