Design

Dropdowns are used to declutter the interface, by holding contextually relevant but lesser-used actions or content. They are often used in the revealing content pattern.

Code

Example Comment Code
The recommended Dropdown trigger is a button. To link a button to its Dropown, add the data-ace-dropdown-trigger attribute with the ID of the Dropdown. No further code is required as the Javascript will initialise automatically. 

                                                                                                      <button class="ace-button ace-button-icon" data-ace-dropdown-trigger="IDOFDROPDOWN" type="button"><span><span class="ace-text">Dropdown menu</span><span class="ace-icon ace-icon-control-arrowdown"></span></span></button>

                                                                                              <% 
                                                                                              ace.DropdownTrigger(Array(_
                                                                                                  "dropdownid", "IDOFDROPDOWN",_
                                                                                                  "text", "Dropdown menu"_
                                                                                              )) 
                                                                                              %>

Icon-only buttons can be used as Dropdown triggers. The menu icon is often used in this configuration.

 

                                                                                                      <button class="ace-button ace-button-icon ace-button-icon" data-ace-dropdown-trigger="IDOFDROPDOWN" type="button"><span><span class="ace-icon ace-icon-control-menu" title="Dropdown menu">Dropdown menu</span></span></button>

                                                                                              <% 
                                                                                              ace.DropdownTrigger(Array(_
                                                                                                  "dropdownid", "IDOFDROPDOWN",_
                                                                                                  "type", "icon",_
                                                                                                  "icon", "control-menu",_
                                                                                                  "iconText", "More actions"_
                                                                                              )) 
                                                                                              %>
12Mb Acrobat PDF

The Dropdown iteself is composed of the dropdown, optional content groups and dropdown menu(s). In its hidden state, the Dropdown should be rendered in the #hidden div at the end of the page, to ensure it does not affect layout.

Right aligned annotations can be added to menu items. These should be very short (1-2 words) to add additional context. They should not contain text that is needed to make a selection.

To set an item's state to active, add the class ace-dropdown-menu-action-active.

 

                                                                                                  <div class="ace-dropdown" id="IDOFDROPDOWN">
                                                                                                        <div class="ace-dropdown-content">
                                                                                                              <div class="ace-dropdown-content-group">
                                                                                                                    <ul class="ace-dropdown-menu">
                                                                                                                          <li class="ace-dropdown-menu-action">
                                                                                                                            <a href="#">Q&amp;A
                                                                                                                            </a>
                                                                                                                          </li>
                                                                                                                          <li class="ace-dropdown-menu-action ace-dropdown-menu-action-active">
                                                                                                                            <a href="#">Reports
                                                                                                                            </a>
                                                                                                                          </li>
                                                                                                                          <li class="ace-dropdown-menu-action">
                                                                                                                            <a href="#">Documents
                                                                                                                            </a>
                                                                                                                          </li>
                                                                                                                    </ul>
                                                                                                              </div>
                                                                                                        </div>
                                                                                                  </div>

                                                                                              <%
                                                                                              ace.Dropdown(Array("id", "IDOFDROPDOWN"))
                                                                                                ace.DropdownContent(Array())
                                                                                                  ace.DropdownContentGroup(Array())
                                                                                                    ace.DropdownMenu(Array())
                                                                                                      ace.DropdownMenuAction(Array(_
                                                                                                        "text", "Q&A"_
                                                                                                      ))
                                                                                                      ace.DropdownMenuAction(Array(_
                                                                                                        "active", true ,_
                                                                                                        "text", "Reports"_
                                                                                                      ))
                                                                                                      ace.DropdownMenuAction(Array(_
                                                                                                        "text", "Documents"_
                                                                                                      ))
                                                                                                    ace.DropdownMenuEnd
                                                                                                  ace.DropdownContentGroupEnd
                                                                                                ace.DropdownContentEnd
                                                                                              ace.DropdownEnd 
                                                                                              %>

Dropdown content groups can have a heading. Add an H3 with the class ace-dropdown-content-heading above the Dropdown Menu.

Dropdown with disabled menu item. Note that disabled items should use a SPAN element, although A is supported in most cases it does not produce the desired result.

This is an amazing new feature that will change your life.

Dropdowns can be used with content other than menus. Use a Dropdown Panel to ensure your content matches the width of menus; or leave it out for completely bespoke use cases. When a Button Group is placed after a Dropdown Panel, it will be right-aligned.

For a self-closing Dropdown, use the 'trigger inside Dropdown' syntax documented below.

 

                                                                                                  <div class="ace-dropdown" id="IDOFDROPDOWN">
                                                                                                        <div class="ace-dropdown-content">
                                                                                                              <div class="ace-dropdown-content-group">
                                                                                                                    <div class="ace-dropdown-panel">
                                                                                                                      <p class="ace-p">This is an amazing new feature that will change your life.</p>
                                                                                                                    </div>
                                                                                                                    <div class="ace-button-group ace-button-group-separate">
                                                                                                                          <button class="ace-button ace-button-link" data-ace-dropdown-trigger="^" type="button"><span>Got it</span></button>
                                                                                                                    </div>
                                                                                                              </div>
                                                                                                        </div>
                                                                                                  </div>

This feature was added to ACE after ACE Classic Templates went into maintenance mode (bugfixes only). By default new ACE features are not supported in Classic, but can be contributed if a specific need is identified.
Tickyboxes

Dropdowns can include top-label forms, inside a dropdown panel. Other form types are too wide and don't fit. All normal form functionality is possible, although be careful not to put too much into a Dropdown when a Dialog or full page view would be more appropriate.

 

                                                                                                  <div class="ace-dropdown" id="IDOFDROPDOWN">
                                                                                                        <div class="ace-dropdown-content">
                                                                                                              <div class="ace-dropdown-panel">
                                                                                                                    <form class="ace-form ace-form-toplabel">
                                                                                                                          <fieldset class="ace-form-group ace-form-group-checkbox">
                                                                                                                                <legend class="ace-form-item ace-assistive ace-form-item-label"><span>Tickyboxes</span></legend>
                                                                                                                                <div class="ace-form-item ace-form-item-input">
                                                                                                                                      <div class="ace-form-input-checkbox-set">
                                                                                                                                            <input class="ace-form-input ace-form-input-checkbox" type="checkbox" name="dropdown-form-content-cb1-code" id="dropdown-form-content-cb1-code">
                                                                                                                                            </input>
                                                                                                                                            <label class="ace-form-label" for="dropdown-form-content-cb1-code"><span class="ace-text">Enable printing</span>
                                                                                                                                            </label>
                                                                                                                                      </div>
                                                                                                                                      <div class="ace-form-input-checkbox-set">
                                                                                                                                            <input class="ace-form-input ace-form-input-checkbox" type="checkbox" name="dropdown-form-content-cb2-code" id="dropdown-form-content-cb2-code">
                                                                                                                                            </input>
                                                                                                                                            <label class="ace-form-label" for="dropdown-form-content-cb2-code"><span class="ace-text">Enable downloads</span>
                                                                                                                                            </label>
                                                                                                                                      </div>
                                                                                                                                </div>
                                                                                                                          </fieldset>
                                                                                                                    </form>
                                                                                                              </div>
                                                                                                        </div>
                                                                                                  </div>

This feature was added to ACE after ACE Classic Templates went into maintenance mode (bugfixes only). By default new ACE features are not supported in Classic, but can be contributed if a specific need is identified.
Single Dropdown with multiple triggers and dynamic content.

By listening to the 'dropdown-open' event on the dropdown, you can change the content of the dropdown dynamically.

The event object will have a 'relatedTarget' property which is the element that triggered the dropdown opening.

Remember to keep in mind that a dropdown can be opened programmically, in which case it will use the last trigger that opened it as the relatedTarget, or null if it hasn't been opened before.


                                                                    (function(){
                                                                      document.getElementById('external-trigger').addEventListener('dropdown-open', function(e){
                                                                        var triggerElement = e.detail.relatedTarget;
                                                                        var dynamicContent = "This dropdown was opened by: " + triggerElement.textContent;
                                                                        if(triggerElement){
                                                                          document.getElementById('external-trigger-content').innerHTML = dynamicContent;
                                                                        }
                                                                      });
                                                                    })();

Most of the time the Dropdown goes in #hidden and the trigger sits elsewhere in the DOM. On some cases it is necessary to render the trigger and dropdown within a single element. In that case, use the special data-ace-dropdown-trigger value ^ to indicate the trigger is opening the parent (^ is pointing up...).

 

                                                                                                  <div class="ace-dropdown" id="IDOFDROPDOWN">
                                                                                                            <button class="ace-button ace-button-icon" data-ace-dropdown-trigger="^" type="button"><span><span class="ace-text">Trigger inside dropdown</span><span class="ace-icon ace-icon-control-arrowdown"></span></span></button>
                                                                                                        <div class="ace-dropdown-content">
                                                                                                              <div class="ace-dropdown-content-group">
                                                                                                                    <ul class="ace-dropdown-menu">
                                                                                                                          <li class="ace-dropdown-menu-action">
                                                                                                                            <a href="#"><span class="ace-icon ace-icon-add-generic"></span><span class="ace-text">Add</span>
                                                                                                                            </a>
                                                                                                                          </li>
                                                                                                                          <li class="ace-dropdown-menu-action">
                                                                                                                            <a href="#"><span class="ace-icon ace-icon-action-remove"></span><span class="ace-text">Remove</span>
                                                                                                                            </a>
                                                                                                                          </li>
                                                                                                                          <li class="ace-dropdown-menu-action">
                                                                                                                            <a href="#"><span class="ace-icon ace-icon-action-download"></span><span class="ace-text">Edit</span>
                                                                                                                            </a>
                                                                                                                          </li>
                                                                                                                    </ul>
                                                                                                              </div>
                                                                                                        </div>
                                                                                                  </div>

                                                                                              <%
                                                                                              ace.Dropdown(Array())
                                                                                                ace.DropdownTrigger(Array(_
                                                                                                    "dropdownid", "^",_
                                                                                                    "text", "Trigger inside dropdown"_
                                                                                                )) 
                                                                                                ace.DropdownContent(Array())
                                                                                                  ace.DropdownContentGroup(Array())
                                                                                                    ace.DropdownMenu(Array())
                                                                                                      ace.DropdownMenuAction(Array(_
                                                                                                        "icon", "add-generic",_
                                                                                                        "text", "Add"_
                                                                                                      ))
                                                                                                      ace.DropdownMenuAction(Array(_
                                                                                                        "icon", "action-remove",_
                                                                                                        "active", true ,_
                                                                                                        "text", "Remove"_
                                                                                                      ))
                                                                                                      ace.DropdownMenuAction(Array(_
                                                                                                        "icon", "action-edit",_
                                                                                                        "text", "Edit"_
                                                                                                      ))
                                                                                                    ace.DropdownMenuEnd
                                                                                                  ace.DropdownContentGroupEnd
                                                                                                ace.DropdownContentEnd
                                                                                              ace.DropdownEnd 
                                                                                              %>
This content should stay within the boundaries of the parent (presuming it fits).

By default, Dropdowns will simply open wherever they fit within the overall viewport.

However this can look strange in some cases:

  • The design calls for a dropdown to fit within a certain area, for example the content area in a fixed-width page.
  • A parent element has overflow, and will cause the dropdown to clip if placed in the wrong place.
  • A parent element has its own scrolling applied, which may mean that the dropdown opens in a hidden area.

By specifying an element as the Dropdown's bounding parent, you can keep the dropdown within the boundary of that element.

Some ACE components like Dialogs are automatically set as boundary elements for dropdowns, so you don't have to manually specify them.

To set an element as a Dropdown's boundary, add the data-ace-dropdown-bounds attribute.

 

                                                                                              <div data-ace-dropdown-bounds="true"></div>

If there is an existing element to use, pass through the attribute:


                                                                                              <%
                                                                                              ace.Foo(Array( _
                                                                                                ...
                                                                                                "data-ace-dropdown-bounds", "true", _
                                                                                                ...
                                                                                              ))
                                                                                              %>

Alternatively just write out the markup:

%><div data-ace-dropdown-bounds="true"></div><%