Skip to content
Primer Design System/React

Primer Design System

Site navigation

On this page

SelectMenu

  • Deprecated
  • Not reviewed for accessibility
On this page
This documentation is moving to a new home. Please update any link or bookmark that points to this page. The new content can be found here.

Deprecation

Use ActionMenu instead.

The SelectMenu components are a suite of components which can be combined together to make several different variations of our GitHub select menu. At it's most basic form, a select menu is comprised of a SelectMenu wrapper, which contains a summary component of your choice and a Select.Modal which contains the select menu content. Use SelectMenu.List to wrap items in the select menu, and SelectMenu.Item to wrap each item.

Several additional components exist to provide even more functionality: SelectMenu.Header, SelectMenu.Filter, SelectMenu.Tabs, SelectMenu.TabPanel SelectMenu.Footer and SelectMenu.Divider.

Basic Example

SelectMenu

Main wrapper component for select menu.

<SelectMenu>{/* all other sub components are wrapped here*/}</SelectMenu>

Component Props

NameTypeDefaultDescription
initialTabStringIf using the SelectMenu.Tabs component, you can use this prop to change the tab shown on open. By default, the first tab will be used.
refReact refref to pass down to SelectMenu component
sxSystemStyleObject{}Style to be applied to the component

SelectMenu.MenuContext

SelectMenu.MenuContext is a context object that exposes some helpful state values to be used via React.useContext in consuming applications. SelectMenu.MenuContext can only be used in components that are already wrapped in a SelectMenu as SelectMenu contains the context provider.

Values available on MenuContext

NameTypeDescription
selectedTabstringThe currently selected tab
setSelectedTabfunctionUsed to update the currently selected tab state
openbooleanState for open/closed status of the menu modal
setOpenfunctionUsed to update the open state
initialTabstringMostly used internally to pass down which tab should be set to open by default. To change this value use the initialTab prop on SelectMenu.

Example Usage

import {SelectMenu, Button} from '@primer/react'
import React, {useContext} from 'react'


const MyMenu = () => (
  <SelectMenu>
    <MyButton />
    <SelectMenu.Modal>content</SelectMenu.Modal>
  </SelectMenu>
)


// note that we can only use the context in components that are already wrapped by SelectMenu (and thus the Context.Provider)
const MyButton = () => {
  const menuContext = useContext(SelectMenu.MenuContext)


  return <Button as="summary">{menuContext.open ? 'Open' : 'Closed'}</Button>
}

SelectMenu.Modal

Used to wrap the content in a SelectMenu.

<SelectMenu.Modal>{/* all menu content is wrapped in the modal*/}</SelectMenu.Modal>

Right-aligned modal

Use the align='right' prop to align the modal to the right. Note that this only modifies alignment for the modal, and not the SelectMenu itself. You will need to wrap the SelectMenu in a relatively positioned element for this to work properly.

Component Props

Prop nameTypeDefaultDescription
alignString'left'Use right to align the select menu to the right
widthString or Number300pxSets the modal width
sxSystemStyleObject{}Style to be applied to the component

SelectMenu.List

Used to wrap the select menu list content. All menu items must be wrapped in a SelectMenu.List in order for the accessibility keyboard handling to function properly. If you are using the SelectMenu.TabPanel you do not need to provide a SelectMenu.List as that component renders a SelectMenu.List as a wrapper.

<SelectMenu.List>{/* all menu  list items are wrapped in the list*/}</SelectMenu.List>

Component Props

NameTypeDefaultDescription
sxSystemStyleObject{}Style to be applied to the component

SelectMenu.Item

Individual items in a select menu. SelectMenu.Item renders an anchor tag by default, you'll need to make sure to provide the appropriate href.

You can use a button tag instead by utilizing the as prop. Be sure to consider which HTML element is the right choice for your usage of the component.

<SelectMenu.Item href="/link/to/thing" selected={true}>
  {/* wraps an individual list item*/}
</SelectMenu.Item>

Component Props

NameTypeDefaultDescription
selectedbooleanUsed to apply styles to the selected items in the list.
onClickfunctionFunction called when item is clicked. By default we also close the menu when items are clicked. If you would like the menu to stay open, pass an e.preventDefault() to your onClick handler.
sxSystemStyleObject{}Style to be applied to the component

SelectMenu.Filter

Use a SelectMenu.Filter to add a filter UI to your select menu. Users are expected to implement their own filtering and manage the state of the value prop on the input. This gives users more flexibility over the type of filtering and type of content passed into each select menu item.

Component Props

SelectMenu.Filter components receive all the props that the TextInput component gets.

NameTypeDefaultDescription
valueStringUsers of this component must provide a value for the filter input that is managed in the consuming application
sxSystemStyleObject{}Style to be applied to the component

SelectMenu.Tabs

Use SelectMenu.Tabs to wrap the tab navigation and SelectMenu.Tab for each tab in the navigation.

SelectMenu.TabPanel should wrap each corresponding panel for each of the tabs. The tabName prop for each SelectMenu.TabPanel must match the name provided in the tabName prop on SelectMenu.Tab.

To set one of the tabs to be open by default, use initialTab on the main SelectMenu component. Otherwise, the first tab will be shown by default.

Each Select.Menu tab will need to have an index prop. The first tab should be at index 0, the second at index 1 and so forth. The index prop is used to show the first tab by default.

If you need access to the selected tab state, you can find it in the MenuContext object exported from SelectMenu as MenuContext.selectedTab.

Component Props

NameTypeDefaultDescription
sxSystemStyleObject{}Style to be applied to the component

SelectMenu.Tab

Used for each individual tab inside of a SelectMenu.Tabs. Be sure to set the index prop to correspond to the order the tab is in. The tabName prop should correspond to the tabName set on the SelectMenu.TabPanel.

The onClick prop is optional and can be used for any events or data fetching you might need to trigger on tab clicks.

<>
  <SelectMenu.Tab index={0} tabName="Repository" />
  <SelectMenu.Tab index={1} tabName="Organization" />
</>

Component Props

NameTypeDefaultDescription
tabNameStringUsed to identify the corresponding tab. Must match the string used in the tabs array in the SelectMenu.Tabs component.
indexNumberThe index at which the tab is in the list of tabs
onClickFunctionFunction to be called when the tab is clicked. Optional.
sxSystemStyleObject{}Style to be applied to the component

SelectMenu.TabPanel

Wraps the content for each tab. Make sure to use the tabName prop to identify each tab panel with the correct tab in the tab navigation.

Note: SelectMenu.TabPanel wraps content in a SelectMenu.List, so adding a SelectMenu.List manually is not necessary.

<SelectMenu.TabPanel tabName="Repository">{/* Wraps content for each tab */}</SelectMenu.TabPanel>

Component Props

NameTypeDefaultDescription
tabNameStringUsed to identify the corresponding tab. Must match the string used in the tabs array in the SelectMenu.Tabs component.
sxSystemStyleObject{}Style to be applied to the component

SelectMenu.Divider

Use a SelectMenu.Divider to add information between items in a SelectMenu.List.

Component Props

NameTypeDefaultDescription
sxSystemStyleObject{}Style to be applied to the component

SelectMenu.Footer

Use a SelectMenu.Footer to add content to the bottom of the select menu.

Component Props

NameTypeDefaultDescription
sxSystemStyleObject{}Style to be applied to the component

SelectMenu.Header

Use a SelectMenu.Header to add a header to the top of the select menu content.

Component Props

NameTypeDefaultDescription
sxSystemStyleObject{}Style to be applied to the component

SelectMenu.LoadingAnimation

Use a SelectMenu.LoadingAnimation to add a loading animation inside of the SelectMenu.

Note: You will need to handle showing/hiding the appropriate modal content for your application during the loading state. We recommend always showing the SelectMenu.Filter and SelectMenu.Header (if used) and hiding the rest of the modal content during the loading state.

Component Props

NameTypeDefaultDescription
sxSystemStyleObject{}Style to be applied to the component