SelectMenu
- Deprecated
- Not reviewed for accessibility
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
| Name | Type | Default | Description |
|---|---|---|---|
| initialTab | String | If 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. | |
| ref | React ref | ref to pass down to SelectMenu component | |
| sx | SystemStyleObject | {} | 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
| Name | Type | Description |
|---|---|---|
| selectedTab | string | The currently selected tab |
| setSelectedTab | function | Used to update the currently selected tab state |
| open | boolean | State for open/closed status of the menu modal |
| setOpen | function | Used to update the open state |
| initialTab | string | Mostly 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 name | Type | Default | Description |
|---|---|---|---|
| align | String | 'left' | Use right to align the select menu to the right |
| width | String or Number | 300px | Sets the modal width |
| sx | SystemStyleObject | {} | 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
| Name | Type | Default | Description |
|---|---|---|---|
| sx | SystemStyleObject | {} | 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
| Name | Type | Default | Description |
|---|---|---|---|
| selected | boolean | Used to apply styles to the selected items in the list. | |
| onClick | function | Function 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. | |
| sx | SystemStyleObject | {} | 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.
| Name | Type | Default | Description |
|---|---|---|---|
| value | String | Users of this component must provide a value for the filter input that is managed in the consuming application | |
| sx | SystemStyleObject | {} | 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
| Name | Type | Default | Description |
|---|---|---|---|
| sx | SystemStyleObject | {} | 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
| Name | Type | Default | Description |
|---|---|---|---|
| tabName | String | Used to identify the corresponding tab. Must match the string used in the tabs array in the SelectMenu.Tabs component. | |
| index | Number | The index at which the tab is in the list of tabs | |
| onClick | Function | Function to be called when the tab is clicked. Optional. | |
| sx | SystemStyleObject | {} | 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
| Name | Type | Default | Description |
|---|---|---|---|
| tabName | String | Used to identify the corresponding tab. Must match the string used in the tabs array in the SelectMenu.Tabs component. | |
| sx | SystemStyleObject | {} | Style to be applied to the component |
SelectMenu.Divider
Use a SelectMenu.Divider to add information between items in a SelectMenu.List.
Component Props
| Name | Type | Default | Description |
|---|---|---|---|
| sx | SystemStyleObject | {} | 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
| Name | Type | Default | Description |
|---|---|---|---|
| sx | SystemStyleObject | {} | 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
| Name | Type | Default | Description |
|---|---|---|---|
| sx | SystemStyleObject | {} | 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
| Name | Type | Default | Description |
|---|---|---|---|
| sx | SystemStyleObject | {} | Style to be applied to the component |
