xmlns:uix="http://projectmallard.org/experimental/ui/"

      type="topic"

      id="drop-down-lists">

  <info>

    <credit type="author">

      <name>Allan Day</name>

      <email>aday@gnome.org</email>

    </credit>

    <link type="guide" xref="ui-elements"/>

    <uix:thumb mime="image/svg" src="figures/ui-elements/drop-down-list.svg"/>

    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"/>

  </info>

<title>Drop-down lists</title>

A drop-down list is a user interface element which allows the user to select from a list of mutually exclusive options. It appears as a button which, when clicked, reveals a list.

<media type="image" mime="image/svg" src="figures/ui-elements/drop-down-list.svg"/>

Radio buttons or a list will often be preferable to a drop-down list, as they present all the available options at once without any further interaction. At the same time, a drop-down list might be a better choice when:

<list>

<item>
The number of options is large.
</item>

<item>
There is little available space.
</item>

<item>
The list of options may change over time.
</item>

<item>
The contents of the hidden part of the menu are obvious from its label and the one selected item. For example, if you have an option menu labelled “Month:” with the item “January” selected, the user might reasonably infer that the menu contains the 12 months of the year without having to look.
</item>

</list>

<section id="general-guidelines">

<title>General guidelines</title>

<list>

<item>
While GTK+ does provide a specific combobox widget, it is recommended that drop-down lists are constructed using a combination of a button and a popover. This allows more comfortable scrolling for long lists, and allows search to be integrated into the list. Using this approach also allows the current selected item to always be displayed.
</item>

<item>
If the number of items is very large, provide a search function that filters the list.
</item>

<item>
Label the drop-down list button with a text label above it or to its left, using <link xref="writing-style#capitalization">sentence capitalization</link>. Provide an access key in the label that allows the user to give focus directly to the drop-down list.
</item>

<item>
Use <link xref="writing-style#capitalization">sentence capitalization</link> for drop-down list items, for example <gui>Switched movement</gui>.
</item>

</list>

</section>

<section id="custom-values">

<title>Custom values</title>

<media type="image" mime="image/svg" src="figures/ui-elements/drop-down-list-custom-values.svg"/>

A drop-down list can allow custom values to be added to a number of presets, or can be used to enter and select from custom values alone.

<list>

<item>
Ensure that custom values are ordered in a way that is most useful to users. Alphabetical or recency ordering is common.
</item>

<item>
When a drop-down list includes both preset and custom values, separate them into separate groups within the list.
</item>

<item>
Allow custom values to be removed from the list.
</item>

<item>
Validate custom values as they are entered, in order to prevent errors.
</item>

<item>
If the drop-down only accepts custom values, and no values have been entered previously, present the custom value entry when the drop-down is opened, instead of showing an empty list.
</item>

</list>

</section>

</page>