Skip to content
Primer/CSS
Design
Interface guidelinesOcticonsPresentationsCommand lineMobileDesktop
Build
CSSReactReact BrandViewComponents
ContributeAbout
On this page

Select menu

  • Beta
  • Not reviewed for accessibility
On this page
Please note that this is a newer version and uses the `.SelectMenu` class instead of the deprecated select menu class. Check the migration guide to make sure your app is up to date.

The SelectMenu component provides advanced support for navigation, filtering, and more. Any menu can make use of JavaScript-enabled live filtering, selected states, tabbed lists, and keyboard navigation with a bit of markup.

Basic example

Use a <details> element to toggle the select menu. The <summary> element can be styled in many ways. In the example below it's a .btn.

Add a .SelectMenu-header to house a clear title and a close button. Note that the close button is only shown on narrow screens (mobile).

Right aligned

In case the select menu should be aligned to the right, use SelectMenu right-0.

Selected state

If the SelectMenu should show a check icon for selected items, use the SelectMenu-icon SelectMenu-icon--check classes. It will make the check icon show when aria-checked="true" is set.

Borderless

Use the .SelectMenu-list--borderless modifier to remove the borders between list items. Note: It's better to keep the borders if a list contains items with multiple lines of text. It will make it easier to see where the items start and end.

Header

Add a .SelectMenu-header at the top to house a clear title and a close button.

List items

The list of items is arguably the most important subcomponent within the menu. Build them out of anchors, buttons, or just about any interactive content. List items are also customizable with options for avatars, additional icons, and multiple lines of text. Use utility classes in case more custom styling is needed.

Divider

The select menu's list can be divided into multiple parts by adding a .SelectMenu-divider. It can be a <div> with text/content. Or just an <hr> to add a visual separator.

Dividers are also supported when using the .SelectMenu-list--borderless modifier.

Footer

Use a .SelectMenu-footer at the bottom for additional information. As a side effect it can greatly improve the scrolling performance because the list doesn't need to be repainted due to the rounded corners.

Filter

If the list is expected to get long, consider adding a .SelectMenu-filter input. Be sure to also include the .SelectMenu--hasFilter modifier class. On mobile devices it will add a fixed height and anchor the select menu to the top of the screen. This makes sure the filter input stays at the same position while typing.

Tabs

Sometimes you need two or more lists of items in your select menu, e.g. branches and tags. Select menu lists can be tabbed with the addition of .SelectMenu-tabs above the menu.

Message

A SelectMenu-message can be used to show different kind of messages to a user. Use utility classes to further style the message.

Loading

When fetching large lists, consider showing a .SelectMenu-loading animation.

Disabled

To disable a list item, use the disabled attribute for <button>s. For <a>s replace the href with an aria-disabled="true" attribute. Note: If not obvious, try to communicate to the user why an item is disabled.

Blankslate

Sometimes a select menu needs to communicate a "blank slate" where there's no content in the menu's list. Usually these include a clear call to action to add said content to the list. Swap out the contents of a .SelectMenu-list with a .SelectMenu-blankslate and customize its contents as needed.

github.com usage

When adding the .SelectMenu component on github.com, use the <details-menu> element. It will magically make the .SelectMenu work. Here a basic example:

<details class="details-reset details-overlay" id="my-select-menu">
  <summary class="btn">
    <span>Choose</span>
    <span class="dropdown-caret"></span>
  </summary>
  <details-menu class="SelectMenu" role="menu">
    <div class="SelectMenu-modal">
      <header class="SelectMenu-header">
        <span class="SelectMenu-title">My Select Menu</span>
        <button class="SelectMenu-closeButton" type="button" data-toggle-for="my-select-menu">
          <%= octicon("x", "aria-label": "Close menu") %>
        </button>
      </header>
      <div class="SelectMenu-list">
        <a class="SelectMenu-item" href="" role="menuitem">Item 1</a>
        <a class="SelectMenu-item" href="" role="menuitem">Item 2</a>
        <a class="SelectMenu-item" href="" role="menuitem">Item 3</a>
      </div>
    </div>
  </details-menu>
</details>

If loading content should be deferred, use the <include-fragment> element:

<details-menu class="SelectMenu" src="/my-menu" preload>
  <div class="SelectMenu-modal">
    <include-fragment class="SelectMenu-loading" aria-label="Menu is loading">
      <%= octicon("octoface", class: "anim-pulse", :height => 32) %>
    </include-fragment>
  </div>
</details-menu>

It will add a pulsing "octoface" icon while the content is loading.

Edit this page on GitHub