<page xmlns="http://projectmallard.org/1.0/"
      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>

<p>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.</p>

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

<p>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:</p>

<list>
<item><p>The number of options is large.</p></item>
<item><p>There is little available space.</p></item>
<item><p>The list of options may change over time.</p></item>
<item><p>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.</p></item>
</list>

<section id="general-guidelines">
<title>General guidelines</title>

<list>
<item><p>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.</p></item>
<item><p>If the number of items is very large, provide a search function that filters the list.</p></item>
<item><p>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.</p></item>
<item><p>Use <link xref="writing-style#capitalization">sentence capitalization</link> for drop-down list items, for example <gui>Switched movement</gui>.</p></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"/>

<p>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.</p>

<list>
<item><p>Ensure that custom values are ordered in a way that is most useful to users. Alphabetical or recency ordering is common.</p></item>
<item><p>When a drop-down list includes both preset and custom values, separate them into separate groups within the list.</p></item>
<item><p>Allow custom values to be removed from the list.</p></item>
<item><p>Validate custom values as they are entered, in order to prevent errors.</p></item>
<item><p>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.</p></item>
</list>

</section>

</page>