SelectPanel

The SelectPanel is an anchored dialog that allows users to quickly navigate and select one or multiple items from a list. It includes a text input for filtering, supports item grouping, and offers a footer for additional actions. Changes are applied upon closing the panel.

Page navigation navigation

React

readyNot reviewed for a11y

Storybook|Source

Rails

readyNot reviewed for a11y

Docs|Lookbook|Source

Figma

View in Figma|

React examples

Single-select

Choice

import React from 'react'
import {Button, FormControl, SelectPanel} from '@primer/react'
import {TriangleDownIcon} from '@primer/octicons-react'
import {type ActionListItemInput} from '@primer/react/deprecated'


const items: ActionListItemInput[] = [
  {text: 'Choice one'},
  {text: 'Choice two'},
  {text: 'Choice three'},
  {text: 'Choice four'},
  {text: 'Choice five'},
]


export default function SingleSelect() {
  const [selected, setSelected] = React.useState<ActionListItemInput | undefined>(items[0])
  const [filter, setFilter] = React.useState('')
  const filteredItems = items.filter(
    item => item.text === selected?.text || item.text?.toLowerCase().startsWith(filter.toLowerCase()),
  )
  // design guidelines say to sort selected items first
  const selectedItemsSortedFirst = filteredItems.sort((a, b) => {
    if (a.text === selected?.text) return -1
    if (b.text === selected?.text) return 1
    return 0
  })
  const [open, setOpen] = React.useState(false)


  return (
    <FormControl>
      <FormControl.Label>Choice</FormControl.Label>
      <SelectPanel
        renderAnchor={({children, ...anchorProps}) => (
          <Button {...anchorProps} trailingAction={TriangleDownIcon} aria-haspopup="dialog">
            {children}
          </Button>
        )}
        placeholder="Pick one choice"
        open={open}
        onOpenChange={setOpen}
        items={selectedItemsSortedFirst}
        selected={selected}
        onSelectedChange={setSelected}
        onFilterChange={setFilter}
      />
    </FormControl>
  )
}

import React from 'react'
import {Button, FormControl, SelectPanel} from '@primer/react'
import {TriangleDownIcon} from '@primer/octicons-react'
import {type ActionListItemInput} from '@primer/react/deprecated'

const items: ActionListItemInput[] = [
  {text: 'Choice one'},
  {text: 'Choice two'},
  {text: 'Choice three'},
  {text: 'Choice four'},
  {text: 'Choice five'},
]

export default function SingleSelect() {
  const [selected, setSelected] = React.useState<ActionListItemInput | undefined>(items[0])
  const [filter, setFilter] = React.useState('')
  const filteredItems = items.filter(
    item => item.text === selected?.text || item.text?.toLowerCase().startsWith(filter.toLowerCase()),
  )
  // design guidelines say to sort selected items first
  const selectedItemsSortedFirst = filteredItems.sort((a, b) => {
    if (a.text === selected?.text) return -1
    if (b.text === selected?.text) return 1
    return 0
  })
  const [open, setOpen] = React.useState(false)

  return (
    <FormControl>
      <FormControl.Label>Choice</FormControl.Label>
      <SelectPanel
        renderAnchor={({children, ...anchorProps}) => (
          <Button {...anchorProps} trailingAction={TriangleDownIcon} aria-haspopup="dialog">
            {children}
          </Button>
        )}
        placeholder="Pick one choice"
        open={open}
        onOpenChange={setOpen}
        items={selectedItemsSortedFirst}
        selected={selected}
        onSelectedChange={setSelected}
        onFilterChange={setFilter}
      />
    </FormControl>
  )
}

Multi-select

When users search for new items, maintain their current selections and use a minimal loading state to indicate ongoing activity.

Choices

import React from 'react'
import {Button, FormControl, SelectPanel} from '@primer/react'
import {TriangleDownIcon} from '@primer/octicons-react'
import {type ActionListItemInput} from '@primer/react/deprecated'


const items: ActionListItemInput[] = [
  {text: 'Choice one'},
  {text: 'Choice two'},
  {text: 'Choice three'},
  {text: 'Choice four'},
  {text: 'Choice five'},
]


export default function MultiSelect() {
  const [selected, setSelected] = React.useState<ActionListItemInput[]>(items.slice(1, 3))
  const [filter, setFilter] = React.useState('')
  const filteredItems = items.filter(
    item =>
      // design guidelines say to always show selected items in the list
      selected.some(selectedItem => selectedItem.text === item.text) ||
      // then filter the rest
      item.text?.toLowerCase().startsWith(filter.toLowerCase()),
  )
  // design guidelines say to sort selected items first
  const selectedItemsSortedFirst = filteredItems.sort((a, b) => {
    const aIsSelected = selected.some(selectedItem => selectedItem.text === a.text)
    const bIsSelected = selected.some(selectedItem => selectedItem.text === b.text)
    if (aIsSelected && !bIsSelected) return -1
    if (!aIsSelected && bIsSelected) return 1
    return 0
  })
  const [open, setOpen] = React.useState(false)


  return (
    <FormControl>
      <FormControl.Label>Choices</FormControl.Label>
      <SelectPanel
        renderAnchor={({children, ...anchorProps}) => (
          <Button {...anchorProps} trailingAction={TriangleDownIcon} aria-haspopup="dialog">
            {children}
          </Button>
        )}
        placeholder="Pick choices"
        open={open}
        onOpenChange={setOpen}
        items={selectedItemsSortedFirst}
        selected={selected}
        onSelectedChange={setSelected}
        onFilterChange={setFilter}
      />
    </FormControl>
  )
}

import React from 'react'
import {Button, FormControl, SelectPanel} from '@primer/react'
import {TriangleDownIcon} from '@primer/octicons-react'
import {type ActionListItemInput} from '@primer/react/deprecated'

const items: ActionListItemInput[] = [
  {text: 'Choice one'},
  {text: 'Choice two'},
  {text: 'Choice three'},
  {text: 'Choice four'},
  {text: 'Choice five'},
]

export default function MultiSelect() {
  const [selected, setSelected] = React.useState<ActionListItemInput[]>(items.slice(1, 3))
  const [filter, setFilter] = React.useState('')
  const filteredItems = items.filter(
    item =>
      // design guidelines say to always show selected items in the list
      selected.some(selectedItem => selectedItem.text === item.text) ||
      // then filter the rest
      item.text?.toLowerCase().startsWith(filter.toLowerCase()),
  )
  // design guidelines say to sort selected items first
  const selectedItemsSortedFirst = filteredItems.sort((a, b) => {
    const aIsSelected = selected.some(selectedItem => selectedItem.text === a.text)
    const bIsSelected = selected.some(selectedItem => selectedItem.text === b.text)
    if (aIsSelected && !bIsSelected) return -1
    if (!aIsSelected && bIsSelected) return 1
    return 0
  })
  const [open, setOpen] = React.useState(false)

  return (
    <FormControl>
      <FormControl.Label>Choices</FormControl.Label>
      <SelectPanel
        renderAnchor={({children, ...anchorProps}) => (
          <Button {...anchorProps} trailingAction={TriangleDownIcon} aria-haspopup="dialog">
            {children}
          </Button>
        )}
        placeholder="Pick choices"
        open={open}
        onOpenChange={setOpen}
        items={selectedItemsSortedFirst}
        selected={selected}
        onSelectedChange={setSelected}
        onFilterChange={setFilter}
      />
    </FormControl>
  )
}

Grouped items

Items can be grouped to provide additional context or to visually separate them. Each group can have a title for better organization.

Selections

import React from 'react'
import {Button, FormControl, SelectPanel} from '@primer/react'
import {TriangleDownIcon} from '@primer/octicons-react'
import {type ActionListGroupedListProps, type ActionListItemInput} from '@primer/react/deprecated'


const items: ActionListItemInput[] = [
  {groupId: '0', text: 'Choice one'},
  {groupId: '0', text: 'Choice two'},
  {groupId: '0', text: 'Choice three'},
  {groupId: '1', text: 'Listing one'},
  {groupId: '1', text: 'Listing two'},
  {groupId: '1', text: 'Listing three'},
  {groupId: '2', text: 'Item one'},
  {groupId: '2', text: 'Item two'},
  {groupId: '2', text: 'Item three'},
]


const groupMetadata: ActionListGroupedListProps['groupMetadata'] = [
  {groupId: '0', header: {title: 'Choices', variant: 'filled'}},
  {groupId: '1', header: {title: 'Listings', variant: 'filled'}},
  {groupId: '2', header: {title: 'Items', variant: 'filled'}},
]


export default function Groups() {
  const [selected, setSelected] = React.useState<ActionListItemInput[]>([items[2], items[5], items[8]])
  const [filter, setFilter] = React.useState('')
  const filteredItems = items.filter(
    item =>
      // design guidelines say to always show selected item in the list
      selected.some(selectedItem => selectedItem.text === item.text) ||
      // then filter the rest
      item.text?.toLowerCase().startsWith(filter.toLowerCase()),
  )
  // design guidelines say to sort selected items first
  const selectedItemsSortedFirst = filteredItems.sort((a, b) => {
    if (a.groupId === b.groupId) {
      const aIsSelected = selected.some(selectedItem => selectedItem.text === a.text)
      const bIsSelected = selected.some(selectedItem => selectedItem.text === b.text)
      if (aIsSelected && !bIsSelected) return -1
      if (!aIsSelected && bIsSelected) return 1
    }
    return 0
  })
  const [open, setOpen] = React.useState(false)


  return (
    <FormControl>
      <FormControl.Label>Selections</FormControl.Label>
      <SelectPanel
        groupMetadata={groupMetadata}
        renderAnchor={({children, ...anchorProps}) => (
          <Button {...anchorProps} trailingAction={TriangleDownIcon} aria-haspopup="dialog">
            {children}
          </Button>
        )}
        placeholder="Pick stuff"
        open={open}
        onOpenChange={setOpen}
        items={selectedItemsSortedFirst}
        selected={selected}
        onSelectedChange={setSelected}
        onFilterChange={setFilter}
      />
    </FormControl>
  )
}

import React from 'react'
import {Button, FormControl, SelectPanel} from '@primer/react'
import {TriangleDownIcon} from '@primer/octicons-react'
import {type ActionListGroupedListProps, type ActionListItemInput} from '@primer/react/deprecated'

const items: ActionListItemInput[] = [
  {groupId: '0', text: 'Choice one'},
  {groupId: '0', text: 'Choice two'},
  {groupId: '0', text: 'Choice three'},
  {groupId: '1', text: 'Listing one'},
  {groupId: '1', text: 'Listing two'},
  {groupId: '1', text: 'Listing three'},
  {groupId: '2', text: 'Item one'},
  {groupId: '2', text: 'Item two'},
  {groupId: '2', text: 'Item three'},
]

const groupMetadata: ActionListGroupedListProps['groupMetadata'] = [
  {groupId: '0', header: {title: 'Choices', variant: 'filled'}},
  {groupId: '1', header: {title: 'Listings', variant: 'filled'}},
  {groupId: '2', header: {title: 'Items', variant: 'filled'}},
]

export default function Groups() {
  const [selected, setSelected] = React.useState<ActionListItemInput[]>([items[2], items[5], items[8]])
  const [filter, setFilter] = React.useState('')
  const filteredItems = items.filter(
    item =>
      // design guidelines say to always show selected item in the list
      selected.some(selectedItem => selectedItem.text === item.text) ||
      // then filter the rest
      item.text?.toLowerCase().startsWith(filter.toLowerCase()),
  )
  // design guidelines say to sort selected items first
  const selectedItemsSortedFirst = filteredItems.sort((a, b) => {
    if (a.groupId === b.groupId) {
      const aIsSelected = selected.some(selectedItem => selectedItem.text === a.text)
      const bIsSelected = selected.some(selectedItem => selectedItem.text === b.text)
      if (aIsSelected && !bIsSelected) return -1
      if (!aIsSelected && bIsSelected) return 1
    }
    return 0
  })
  const [open, setOpen] = React.useState(false)

  return (
    <FormControl>
      <FormControl.Label>Selections</FormControl.Label>
      <SelectPanel
        groupMetadata={groupMetadata}
        renderAnchor={({children, ...anchorProps}) => (
          <Button {...anchorProps} trailingAction={TriangleDownIcon} aria-haspopup="dialog">
            {children}
          </Button>
        )}
        placeholder="Pick stuff"
        open={open}
        onOpenChange={setOpen}
        items={selectedItemsSortedFirst}
        selected={selected}
        onSelectedChange={setSelected}
        onFilterChange={setFilter}
      />
    </FormControl>
  )
}

Items with leading visuals

Software

import React from 'react'
import {Avatar, Button, FormControl, SelectPanel} from '@primer/react'
import {TriangleDownIcon} from '@primer/octicons-react'
import {type ActionListItemInput} from '@primer/react/deprecated'
;<Avatar alt="Atom logo" src="https://avatars.githubusercontent.com/atom" />


const items: ActionListItemInput[] = [
  {
    leadingVisual: () => <Avatar alt="GitHub logo" size={16} src="https://avatars.githubusercontent.com/github" />,
    text: 'GitHub',
  },
  {
    leadingVisual: () => <Avatar alt="Primer logo" size={16} src="https://avatars.githubusercontent.com/primer" />,
    text: 'Primer',
  },
  {
    leadingVisual: () => <Avatar alt="Atom logo" size={16} src="https://avatars.githubusercontent.com/atom" />,
    text: 'Atom',
  },
]


export default function LeadingVisual() {
  const [selected, setSelected] = React.useState<ActionListItemInput[]>(items.slice(1, 3))
  const [filter, setFilter] = React.useState('')
  const filteredItems = items.filter(
    item =>
      // design guidelines say to always show selected items in the list
      selected.some(selectedItem => selectedItem.text === item.text) ||
      // then filter the rest
      item.text?.toLowerCase().startsWith(filter.toLowerCase()),
  )
  // design guidelines say to sort selected items first
  const selectedItemsSortedFirst = filteredItems.sort((a, b) => {
    const aIsSelected = selected.some(selectedItem => selectedItem.text === a.text)
    const bIsSelected = selected.some(selectedItem => selectedItem.text === b.text)
    if (aIsSelected && !bIsSelected) return -1
    if (!aIsSelected && bIsSelected) return 1
    return 0
  })
  const [open, setOpen] = React.useState(false)


  return (
    <FormControl>
      <FormControl.Label>Software</FormControl.Label>
      <SelectPanel
        renderAnchor={({children, ...anchorProps}) => (
          <Button {...anchorProps} trailingAction={TriangleDownIcon} aria-haspopup="dialog">
            {children}
          </Button>
        )}
        placeholder="Pick software"
        open={open}
        onOpenChange={setOpen}
        items={selectedItemsSortedFirst}
        selected={selected}
        onSelectedChange={setSelected}
        onFilterChange={setFilter}
      />
    </FormControl>
  )
}

import React from 'react'
import {Avatar, Button, FormControl, SelectPanel} from '@primer/react'
import {TriangleDownIcon} from '@primer/octicons-react'
import {type ActionListItemInput} from '@primer/react/deprecated'
;<Avatar alt="Atom logo" src="https://avatars.githubusercontent.com/atom" />

const items: ActionListItemInput[] = [
  {
    leadingVisual: () => <Avatar alt="GitHub logo" size={16} src="https://avatars.githubusercontent.com/github" />,
    text: 'GitHub',
  },
  {
    leadingVisual: () => <Avatar alt="Primer logo" size={16} src="https://avatars.githubusercontent.com/primer" />,
    text: 'Primer',
  },
  {
    leadingVisual: () => <Avatar alt="Atom logo" size={16} src="https://avatars.githubusercontent.com/atom" />,
    text: 'Atom',
  },
]

export default function LeadingVisual() {
  const [selected, setSelected] = React.useState<ActionListItemInput[]>(items.slice(1, 3))
  const [filter, setFilter] = React.useState('')
  const filteredItems = items.filter(
    item =>
      // design guidelines say to always show selected items in the list
      selected.some(selectedItem => selectedItem.text === item.text) ||
      // then filter the rest
      item.text?.toLowerCase().startsWith(filter.toLowerCase()),
  )
  // design guidelines say to sort selected items first
  const selectedItemsSortedFirst = filteredItems.sort((a, b) => {
    const aIsSelected = selected.some(selectedItem => selectedItem.text === a.text)
    const bIsSelected = selected.some(selectedItem => selectedItem.text === b.text)
    if (aIsSelected && !bIsSelected) return -1
    if (!aIsSelected && bIsSelected) return 1
    return 0
  })
  const [open, setOpen] = React.useState(false)

  return (
    <FormControl>
      <FormControl.Label>Software</FormControl.Label>
      <SelectPanel
        renderAnchor={({children, ...anchorProps}) => (
          <Button {...anchorProps} trailingAction={TriangleDownIcon} aria-haspopup="dialog">
            {children}
          </Button>
        )}
        placeholder="Pick software"
        open={open}
        onOpenChange={setOpen}
        items={selectedItemsSortedFirst}
        selected={selected}
        onSelectedChange={setSelected}
        onFilterChange={setFilter}
      />
    </FormControl>
  )
}

Items with dividers

Choices

import React from 'react'
import {Button, FormControl, SelectPanel} from '@primer/react'
import {TriangleDownIcon} from '@primer/octicons-react'
import {type ActionListItemInput} from '@primer/react/deprecated'


const items: ActionListItemInput[] = [
  {text: 'Choice one'},
  {text: 'Choice two'},
  {text: 'Choice three'},
  {text: 'Choice four'},
  {text: 'Choice five'},
]


export default function Dividers() {
  const [selected, setSelected] = React.useState<ActionListItemInput[]>(items.slice(1, 3))
  const [filter, setFilter] = React.useState('')
  const filteredItems = items.filter(
    item =>
      // design guidelines say to always show selected items in the list
      selected.some(selectedItem => selectedItem.text === item.text) ||
      // then filter the rest
      item.text?.toLowerCase().startsWith(filter.toLowerCase()),
  )
  // design guidelines say to sort selected items first
  const selectedItemsSortedFirst = filteredItems.sort((a, b) => {
    const aIsSelected = selected.some(selectedItem => selectedItem.text === a.text)
    const bIsSelected = selected.some(selectedItem => selectedItem.text === b.text)
    if (aIsSelected && !bIsSelected) return -1
    if (!aIsSelected && bIsSelected) return 1
    return 0
  })
  const [open, setOpen] = React.useState(false)


  return (
    <FormControl>
      <FormControl.Label>Choices</FormControl.Label>
      <SelectPanel
        showItemDividers
        renderAnchor={({children, ...anchorProps}) => (
          <Button {...anchorProps} trailingAction={TriangleDownIcon} aria-haspopup="dialog">
            {children}
          </Button>
        )}
        placeholder="Pick choices"
        open={open}
        onOpenChange={setOpen}
        items={selectedItemsSortedFirst}
        selected={selected}
        onSelectedChange={setSelected}
        onFilterChange={setFilter}
      />
    </FormControl>
  )
}

import React from 'react'
import {Button, FormControl, SelectPanel} from '@primer/react'
import {TriangleDownIcon} from '@primer/octicons-react'
import {type ActionListItemInput} from '@primer/react/deprecated'

const items: ActionListItemInput[] = [
  {text: 'Choice one'},
  {text: 'Choice two'},
  {text: 'Choice three'},
  {text: 'Choice four'},
  {text: 'Choice five'},
]

export default function Dividers() {
  const [selected, setSelected] = React.useState<ActionListItemInput[]>(items.slice(1, 3))
  const [filter, setFilter] = React.useState('')
  const filteredItems = items.filter(
    item =>
      // design guidelines say to always show selected items in the list
      selected.some(selectedItem => selectedItem.text === item.text) ||
      // then filter the rest
      item.text?.toLowerCase().startsWith(filter.toLowerCase()),
  )
  // design guidelines say to sort selected items first
  const selectedItemsSortedFirst = filteredItems.sort((a, b) => {
    const aIsSelected = selected.some(selectedItem => selectedItem.text === a.text)
    const bIsSelected = selected.some(selectedItem => selectedItem.text === b.text)
    if (aIsSelected && !bIsSelected) return -1
    if (!aIsSelected && bIsSelected) return 1
    return 0
  })
  const [open, setOpen] = React.useState(false)

  return (
    <FormControl>
      <FormControl.Label>Choices</FormControl.Label>
      <SelectPanel
        showItemDividers
        renderAnchor={({children, ...anchorProps}) => (
          <Button {...anchorProps} trailingAction={TriangleDownIcon} aria-haspopup="dialog">
            {children}
          </Button>
        )}
        placeholder="Pick choices"
        open={open}
        onOpenChange={setOpen}
        items={selectedItemsSortedFirst}
        selected={selected}
        onSelectedChange={setSelected}
        onFilterChange={setFilter}
      />
    </FormControl>
  )
}

With header

Choices

import React from 'react'
import {Button, FormControl, SelectPanel} from '@primer/react'
import {TriangleDownIcon} from '@primer/octicons-react'
import {type ActionListItemInput} from '@primer/react/deprecated'


const items: ActionListItemInput[] = [
  {text: 'Choice one'},
  {text: 'Choice two'},
  {text: 'Choice three'},
  {text: 'Choice four'},
  {text: 'Choice five'},
]


export default function Header() {
  const [selected, setSelected] = React.useState<ActionListItemInput[]>(items.slice(1, 3))
  const [filter, setFilter] = React.useState('')
  const filteredItems = items.filter(
    item =>
      // design guidelines say to always show selected items in the list
      selected.some(selectedItem => selectedItem.text === item.text) ||
      // then filter the rest
      item.text?.toLowerCase().startsWith(filter.toLowerCase()),
  )
  // design guidelines say to sort selected items first
  const selectedItemsSortedFirst = filteredItems.sort((a, b) => {
    const aIsSelected = selected.some(selectedItem => selectedItem.text === a.text)
    const bIsSelected = selected.some(selectedItem => selectedItem.text === b.text)
    if (aIsSelected && !bIsSelected) return -1
    if (!aIsSelected && bIsSelected) return 1
    return 0
  })
  const [open, setOpen] = React.useState(false)


  return (
    <FormControl>
      <FormControl.Label>Choices</FormControl.Label>
      <SelectPanel
        title="Choice list"
        subtitle="Pick as many choices as you want."
        renderAnchor={({children, ...anchorProps}) => (
          <Button {...anchorProps} trailingAction={TriangleDownIcon} aria-haspopup="dialog">
            {children}
          </Button>
        )}
        placeholder="Pick choices"
        open={open}
        onOpenChange={setOpen}
        items={selectedItemsSortedFirst}
        selected={selected}
        onSelectedChange={setSelected}
        onFilterChange={setFilter}
      />
    </FormControl>
  )
}

import React from 'react'
import {Button, FormControl, SelectPanel} from '@primer/react'
import {TriangleDownIcon} from '@primer/octicons-react'
import {type ActionListItemInput} from '@primer/react/deprecated'

const items: ActionListItemInput[] = [
  {text: 'Choice one'},
  {text: 'Choice two'},
  {text: 'Choice three'},
  {text: 'Choice four'},
  {text: 'Choice five'},
]

export default function Header() {
  const [selected, setSelected] = React.useState<ActionListItemInput[]>(items.slice(1, 3))
  const [filter, setFilter] = React.useState('')
  const filteredItems = items.filter(
    item =>
      // design guidelines say to always show selected items in the list
      selected.some(selectedItem => selectedItem.text === item.text) ||
      // then filter the rest
      item.text?.toLowerCase().startsWith(filter.toLowerCase()),
  )
  // design guidelines say to sort selected items first
  const selectedItemsSortedFirst = filteredItems.sort((a, b) => {
    const aIsSelected = selected.some(selectedItem => selectedItem.text === a.text)
    const bIsSelected = selected.some(selectedItem => selectedItem.text === b.text)
    if (aIsSelected && !bIsSelected) return -1
    if (!aIsSelected && bIsSelected) return 1
    return 0
  })
  const [open, setOpen] = React.useState(false)

  return (
    <FormControl>
      <FormControl.Label>Choices</FormControl.Label>
      <SelectPanel
        title="Choice list"
        subtitle="Pick as many choices as you want."
        renderAnchor={({children, ...anchorProps}) => (
          <Button {...anchorProps} trailingAction={TriangleDownIcon} aria-haspopup="dialog">
            {children}
          </Button>
        )}
        placeholder="Pick choices"
        open={open}
        onOpenChange={setOpen}
        items={selectedItemsSortedFirst}
        selected={selected}
        onSelectedChange={setSelected}
        onFilterChange={setFilter}
      />
    </FormControl>
  )
}

An optional footer at the bottom can include a link or button for additional actions.

Choices

import React from 'react'
import {Button, FormControl, SelectPanel} from '@primer/react'
import {TriangleDownIcon} from '@primer/octicons-react'
import {type ActionListItemInput} from '@primer/react/deprecated'


const items: ActionListItemInput[] = [
  {text: 'Choice one'},
  {text: 'Choice two'},
  {text: 'Choice three'},
  {text: 'Choice four'},
  {text: 'Choice five'},
]


export default function Footer() {
  const [selected, setSelected] = React.useState<ActionListItemInput[]>(items.slice(1, 3))
  const [filter, setFilter] = React.useState('')
  const filteredItems = items.filter(
    item =>
      // design guidelines say to always show selected items in the list
      selected.some(selectedItem => selectedItem.text === item.text) ||
      // then filter the rest
      item.text?.toLowerCase().startsWith(filter.toLowerCase()),
  )
  // design guidelines say to sort selected items first
  const selectedItemsSortedFirst = filteredItems.sort((a, b) => {
    const aIsSelected = selected.some(selectedItem => selectedItem.text === a.text)
    const bIsSelected = selected.some(selectedItem => selectedItem.text === b.text)
    if (aIsSelected && !bIsSelected) return -1
    if (!aIsSelected && bIsSelected) return 1
    return 0
  })
  const [open, setOpen] = React.useState(false)


  return (
    <FormControl>
      <FormControl.Label>Choices</FormControl.Label>
      <SelectPanel
        renderAnchor={({children, ...anchorProps}) => (
          <Button {...anchorProps} trailingAction={TriangleDownIcon} aria-haspopup="dialog">
            {children}
          </Button>
        )}
        placeholder="Pick choices"
        open={open}
        onOpenChange={setOpen}
        items={selectedItemsSortedFirst}
        selected={selected}
        onSelectedChange={setSelected}
        onFilterChange={setFilter}
        footer={
          <Button size="small" block onClick={() => alert('fake edit mode toggle')}>
            Edit choices
          </Button>
        }
      />
    </FormControl>
  )
}

import React from 'react'
import {Button, FormControl, SelectPanel} from '@primer/react'
import {TriangleDownIcon} from '@primer/octicons-react'
import {type ActionListItemInput} from '@primer/react/deprecated'

const items: ActionListItemInput[] = [
  {text: 'Choice one'},
  {text: 'Choice two'},
  {text: 'Choice three'},
  {text: 'Choice four'},
  {text: 'Choice five'},
]

export default function Footer() {
  const [selected, setSelected] = React.useState<ActionListItemInput[]>(items.slice(1, 3))
  const [filter, setFilter] = React.useState('')
  const filteredItems = items.filter(
    item =>
      // design guidelines say to always show selected items in the list
      selected.some(selectedItem => selectedItem.text === item.text) ||
      // then filter the rest
      item.text?.toLowerCase().startsWith(filter.toLowerCase()),
  )
  // design guidelines say to sort selected items first
  const selectedItemsSortedFirst = filteredItems.sort((a, b) => {
    const aIsSelected = selected.some(selectedItem => selectedItem.text === a.text)
    const bIsSelected = selected.some(selectedItem => selectedItem.text === b.text)
    if (aIsSelected && !bIsSelected) return -1
    if (!aIsSelected && bIsSelected) return 1
    return 0
  })
  const [open, setOpen] = React.useState(false)

  return (
    <FormControl>
      <FormControl.Label>Choices</FormControl.Label>
      <SelectPanel
        renderAnchor={({children, ...anchorProps}) => (
          <Button {...anchorProps} trailingAction={TriangleDownIcon} aria-haspopup="dialog">
            {children}
          </Button>
        )}
        placeholder="Pick choices"
        open={open}
        onOpenChange={setOpen}
        items={selectedItemsSortedFirst}
        selected={selected}
        onSelectedChange={setSelected}
        onFilterChange={setFilter}
        footer={
          <Button size="small" block onClick={() => alert('fake edit mode toggle')}>
            Edit choices
          </Button>
        }
      />
    </FormControl>
  )
}

Loading

Provide visual cues to users when processes may take longer than expected. Use loading states to communicate results are loading. Use when retrieving initial data to prevent users from seeing an empty list.

import React from 'react'
import {Button, SelectPanel} from '@primer/react'
import {TriangleDownIcon} from '@primer/octicons-react'
import {type ActionListItemInput} from '@primer/react/deprecated'


const items: ActionListItemInput[] = [
  {text: 'Choice one'},
  {text: 'Choice two'},
  {text: 'Choice three'},
  {text: 'Choice four'},
  {text: 'Choice five'},
]


export default function Loading() {
  const [selected, setSelected] = React.useState<ActionListItemInput | undefined>(items[0])
  const [filter, setFilter] = React.useState('')
  const filteredItems = items.filter(
    item => item.text === selected?.text || item.text?.toLowerCase().startsWith(filter.toLowerCase()),
  )
  // design guidelines say to sort selected items first
  const selectedItemsSortedFirst = filteredItems.sort((a, b) => {
    if (a.text === selected?.text) return -1
    if (b.text === selected?.text) return 1
    return 0
  })
  const [open, setOpen] = React.useState(false)


  return (
    <SelectPanel
      loading={true}
      title="Select labels"
      subtitle="Use labels to organize issues and pull requests"
      renderAnchor={({children, 'aria-labelledby': ariaLabelledBy, ...anchorProps}) => (
        <Button
          trailingAction={TriangleDownIcon}
          aria-labelledby={` ${ariaLabelledBy}`}
          {...anchorProps}
          aria-haspopup="dialog"
        >
          {children ?? 'Select Labels'}
        </Button>
      )}
      placeholderText="Filter labels"
      open={open}
      onOpenChange={setOpen}
      items={selectedItemsSortedFirst}
      selected={selected}
      onSelectedChange={setSelected}
      onFilterChange={setFilter}
    />
  )
}

import React from 'react'
import {Button, SelectPanel} from '@primer/react'
import {TriangleDownIcon} from '@primer/octicons-react'
import {type ActionListItemInput} from '@primer/react/deprecated'

const items: ActionListItemInput[] = [
  {text: 'Choice one'},
  {text: 'Choice two'},
  {text: 'Choice three'},
  {text: 'Choice four'},
  {text: 'Choice five'},
]

export default function Loading() {
  const [selected, setSelected] = React.useState<ActionListItemInput | undefined>(items[0])
  const [filter, setFilter] = React.useState('')
  const filteredItems = items.filter(
    item => item.text === selected?.text || item.text?.toLowerCase().startsWith(filter.toLowerCase()),
  )
  // design guidelines say to sort selected items first
  const selectedItemsSortedFirst = filteredItems.sort((a, b) => {
    if (a.text === selected?.text) return -1
    if (b.text === selected?.text) return 1
    return 0
  })
  const [open, setOpen] = React.useState(false)

  return (
    <SelectPanel
      loading={true}
      title="Select labels"
      subtitle="Use labels to organize issues and pull requests"
      renderAnchor={({children, 'aria-labelledby': ariaLabelledBy, ...anchorProps}) => (
        <Button
          trailingAction={TriangleDownIcon}
          aria-labelledby={` ${ariaLabelledBy}`}
          {...anchorProps}
          aria-haspopup="dialog"
        >
          {children ?? 'Select Labels'}
        </Button>
      )}
      placeholderText="Filter labels"
      open={open}
      onOpenChange={setOpen}
      items={selectedItemsSortedFirst}
      selected={selected}
      onSelectedChange={setSelected}
      onFilterChange={setFilter}
    />
  )
}

Other label options

If the button represents the current selection, it must have an associated label, either internally (within the button) or externally (adjacent to the button).

Choices

import React from 'react'
import {Button, FormControl, SelectPanel} from '@primer/react'
import {TriangleDownIcon} from '@primer/octicons-react'
import {type ActionListItemInput} from '@primer/react/deprecated'


const items: ActionListItemInput[] = [
  {text: 'Choice one'},
  {text: 'Choice two'},
  {text: 'Choice three'},
  {text: 'Choice four'},
  {text: 'Choice five'},
]


export default function LabelHidden() {
  const [selected, setSelected] = React.useState<ActionListItemInput[]>(items.slice(1, 3))
  const [filter, setFilter] = React.useState('')
  const filteredItems = items.filter(
    item =>
      // design guidelines say to always show selected items in the list
      selected.some(selectedItem => selectedItem.text === item.text) ||
      // then filter the rest
      item.text?.toLowerCase().startsWith(filter.toLowerCase()),
  )
  // design guidelines say to sort selected items first
  const selectedItemsSortedFirst = filteredItems.sort((a, b) => {
    const aIsSelected = selected.some(selectedItem => selectedItem.text === a.text)
    const bIsSelected = selected.some(selectedItem => selectedItem.text === b.text)
    if (aIsSelected && !bIsSelected) return -1
    if (!aIsSelected && bIsSelected) return 1
    return 0
  })
  const [open, setOpen] = React.useState(false)


  return (
    <FormControl>
      <FormControl.Label visuallyHidden>Choices</FormControl.Label>
      <SelectPanel
        renderAnchor={({children, ...anchorProps}) => (
          <Button {...anchorProps} trailingAction={TriangleDownIcon} aria-haspopup="dialog">
            {children}
          </Button>
        )}
        placeholder="Pick choices"
        open={open}
        onOpenChange={setOpen}
        items={selectedItemsSortedFirst}
        selected={selected}
        onSelectedChange={setSelected}
        onFilterChange={setFilter}
      />
    </FormControl>
  )
}

import React from 'react'
import {Button, FormControl, SelectPanel} from '@primer/react'
import {TriangleDownIcon} from '@primer/octicons-react'
import {type ActionListItemInput} from '@primer/react/deprecated'

const items: ActionListItemInput[] = [
  {text: 'Choice one'},
  {text: 'Choice two'},
  {text: 'Choice three'},
  {text: 'Choice four'},
  {text: 'Choice five'},
]

export default function LabelHidden() {
  const [selected, setSelected] = React.useState<ActionListItemInput[]>(items.slice(1, 3))
  const [filter, setFilter] = React.useState('')
  const filteredItems = items.filter(
    item =>
      // design guidelines say to always show selected items in the list
      selected.some(selectedItem => selectedItem.text === item.text) ||
      // then filter the rest
      item.text?.toLowerCase().startsWith(filter.toLowerCase()),
  )
  // design guidelines say to sort selected items first
  const selectedItemsSortedFirst = filteredItems.sort((a, b) => {
    const aIsSelected = selected.some(selectedItem => selectedItem.text === a.text)
    const bIsSelected = selected.some(selectedItem => selectedItem.text === b.text)
    if (aIsSelected && !bIsSelected) return -1
    if (!aIsSelected && bIsSelected) return 1
    return 0
  })
  const [open, setOpen] = React.useState(false)

  return (
    <FormControl>
      <FormControl.Label visuallyHidden>Choices</FormControl.Label>
      <SelectPanel
        renderAnchor={({children, ...anchorProps}) => (
          <Button {...anchorProps} trailingAction={TriangleDownIcon} aria-haspopup="dialog">
            {children}
          </Button>
        )}
        placeholder="Pick choices"
        open={open}
        onOpenChange={setOpen}
        items={selectedItemsSortedFirst}
        selected={selected}
        onSelectedChange={setSelected}
        onFilterChange={setFilter}
      />
    </FormControl>
  )
}

Internal label

import React from 'react'
import {Box, Button, SelectPanel} from '@primer/react'
import {TriangleDownIcon} from '@primer/octicons-react'
import {type ActionListItemInput} from '@primer/react/deprecated'


const items: ActionListItemInput[] = [
  {text: 'Choice one'},
  {text: 'Choice two'},
  {text: 'Choice three'},
  {text: 'Choice four'},
  {text: 'Choice five'},
]


export default function LabelInternal() {
  const [selected, setSelected] = React.useState<ActionListItemInput[]>(items.slice(1, 3))
  const [filter, setFilter] = React.useState('')
  const filteredItems = items.filter(
    item =>
      // design guidelines say to always show selected items in the list
      selected.some(selectedItem => selectedItem.text === item.text) ||
      // then filter the rest
      item.text?.toLowerCase().startsWith(filter.toLowerCase()),
  )
  // design guidelines say to sort selected items first
  const selectedItemsSortedFirst = filteredItems.sort((a, b) => {
    const aIsSelected = selected.some(selectedItem => selectedItem.text === a.text)
    const bIsSelected = selected.some(selectedItem => selectedItem.text === b.text)
    if (aIsSelected && !bIsSelected) return -1
    if (!aIsSelected && bIsSelected) return 1
    return 0
  })
  const [open, setOpen] = React.useState(false)


  return (
    <SelectPanel
      renderAnchor={({children, ...anchorProps}) => (
        <Button {...anchorProps} trailingAction={TriangleDownIcon} aria-haspopup="dialog">
          <Box
            sx={{
              color: 'var(--fgColor-muted)',
              display: 'inline-block',
            }}
          >
            Choices:
          </Box>{' '}
          {children || 'None selected'}
        </Button>
      )}
      placeholder="Pick choices"
      open={open}
      onOpenChange={setOpen}
      items={selectedItemsSortedFirst}
      selected={selected}
      onSelectedChange={setSelected}
      onFilterChange={setFilter}
    />
  )
}

import React from 'react'
import {Box, Button, SelectPanel} from '@primer/react'
import {TriangleDownIcon} from '@primer/octicons-react'
import {type ActionListItemInput} from '@primer/react/deprecated'

const items: ActionListItemInput[] = [
  {text: 'Choice one'},
  {text: 'Choice two'},
  {text: 'Choice three'},
  {text: 'Choice four'},
  {text: 'Choice five'},
]

export default function LabelInternal() {
  const [selected, setSelected] = React.useState<ActionListItemInput[]>(items.slice(1, 3))
  const [filter, setFilter] = React.useState('')
  const filteredItems = items.filter(
    item =>
      // design guidelines say to always show selected items in the list
      selected.some(selectedItem => selectedItem.text === item.text) ||
      // then filter the rest
      item.text?.toLowerCase().startsWith(filter.toLowerCase()),
  )
  // design guidelines say to sort selected items first
  const selectedItemsSortedFirst = filteredItems.sort((a, b) => {
    const aIsSelected = selected.some(selectedItem => selectedItem.text === a.text)
    const bIsSelected = selected.some(selectedItem => selectedItem.text === b.text)
    if (aIsSelected && !bIsSelected) return -1
    if (!aIsSelected && bIsSelected) return 1
    return 0
  })
  const [open, setOpen] = React.useState(false)

  return (
    <SelectPanel
      renderAnchor={({children, ...anchorProps}) => (
        <Button {...anchorProps} trailingAction={TriangleDownIcon} aria-haspopup="dialog">
          <Box
            sx={{
              color: 'var(--fgColor-muted)',
              display: 'inline-block',
            }}
          >
            Choices:
          </Box>{' '}
          {children || 'None selected'}
        </Button>
      )}
      placeholder="Pick choices"
      open={open}
      onOpenChange={setOpen}
      items={selectedItemsSortedFirst}
      selected={selected}
      onSelectedChange={setSelected}
      onFilterChange={setFilter}
    />
  )
}

Custom (external) anchor

To use an external anchor, pass an anchorRef to SelectPanel. You will also need to manually toggle the open prop when activating the custom anchor.

Choices

import React from 'react'
import {Button, FormControl, SelectPanel} from '@primer/react'
import {TriangleDownIcon} from '@primer/octicons-react'
import {type ActionListItemInput} from '@primer/react/deprecated'


const items: ActionListItemInput[] = [
  {text: 'Choice one'},
  {text: 'Choice two'},
  {text: 'Choice three'},
  {text: 'Choice four'},
  {text: 'Choice five'},
]


export default function MultiSelect() {
  const buttonRef = React.useRef<HTMLButtonElement>(null)
  const [selected, setSelected] = React.useState<ActionListItemInput[]>(items.slice(1, 3))
  const [filter, setFilter] = React.useState('')
  const filteredItems = items.filter(
    item =>
      // design guidelines say to always show selected items in the list
      selected.some(selectedItem => selectedItem.text === item.text) ||
      // then filter the rest
      item.text?.toLowerCase().startsWith(filter.toLowerCase()),
  )
  // design guidelines say to sort selected items first
  const selectedItemsSortedFirst = filteredItems.sort((a, b) => {
    const aIsSelected = selected.some(selectedItem => selectedItem.text === a.text)
    const bIsSelected = selected.some(selectedItem => selectedItem.text === b.text)
    if (aIsSelected && !bIsSelected) return -1
    if (!aIsSelected && bIsSelected) return 1
    return 0
  })
  const [open, setOpen] = React.useState(false)


  return (
    <FormControl>
      <FormControl.Label>Choices</FormControl.Label>
      <Button trailingAction={TriangleDownIcon} ref={buttonRef} onClick={() => setOpen(!open)}>
        {selected.map(selectedItem => selectedItem.text).join(', ') || 'Pick choices'}
      </Button>
      <SelectPanel
        anchorRef={buttonRef}
        renderAnchor={null}
        open={open}
        onOpenChange={setOpen}
        items={selectedItemsSortedFirst}
        selected={selected}
        onSelectedChange={setSelected}
        onFilterChange={setFilter}
      />
    </FormControl>
  )
}

import React from 'react'
import {Button, FormControl, SelectPanel} from '@primer/react'
import {TriangleDownIcon} from '@primer/octicons-react'
import {type ActionListItemInput} from '@primer/react/deprecated'

const items: ActionListItemInput[] = [
  {text: 'Choice one'},
  {text: 'Choice two'},
  {text: 'Choice three'},
  {text: 'Choice four'},
  {text: 'Choice five'},
]

export default function MultiSelect() {
  const buttonRef = React.useRef<HTMLButtonElement>(null)
  const [selected, setSelected] = React.useState<ActionListItemInput[]>(items.slice(1, 3))
  const [filter, setFilter] = React.useState('')
  const filteredItems = items.filter(
    item =>
      // design guidelines say to always show selected items in the list
      selected.some(selectedItem => selectedItem.text === item.text) ||
      // then filter the rest
      item.text?.toLowerCase().startsWith(filter.toLowerCase()),
  )
  // design guidelines say to sort selected items first
  const selectedItemsSortedFirst = filteredItems.sort((a, b) => {
    const aIsSelected = selected.some(selectedItem => selectedItem.text === a.text)
    const bIsSelected = selected.some(selectedItem => selectedItem.text === b.text)
    if (aIsSelected && !bIsSelected) return -1
    if (!aIsSelected && bIsSelected) return 1
    return 0
  })
  const [open, setOpen] = React.useState(false)

  return (
    <FormControl>
      <FormControl.Label>Choices</FormControl.Label>
      <Button trailingAction={TriangleDownIcon} ref={buttonRef} onClick={() => setOpen(!open)}>
        {selected.map(selectedItem => selectedItem.text).join(', ') || 'Pick choices'}
      </Button>
      <SelectPanel
        anchorRef={buttonRef}
        renderAnchor={null}
        open={open}
        onOpenChange={setOpen}
        items={selectedItemsSortedFirst}
        selected={selected}
        onSelectedChange={setSelected}
        onFilterChange={setFilter}
      />
    </FormControl>
  )
}

Props

SelectPanel

Name	Default	Description
items Required		`ItemInput[]` A collection of `Item` props and `Item`-level custom `Item` renderers.
title	`"Select an item" or "Select items"`	`string \| React.ReactElement` A descriptive title for the panel
subtitle		`string \| React.ReactElement` When provided, a subtitle is displayed below the title
onOpenChange Required		`( open: boolean, gesture: \| 'anchor-click' \| 'anchor-key-press' \| 'click-outside' \| 'escape' \| 'selection' ) => void`
placeholder		`string` Text used in anchor when there are no selected items
placeholderText	`Filter items`	`string` Text used as placeholder for search input
inputLabel	`Same as placeholderText`	`string` The aria-label for the filter input
aria-label		`string` aria-label to attach to the base DOM node of the list
filterValue		`string` The current value of the search input
selected Required		`ItemInput \| ItemInput[] \| undefined` Specify the selected item(s)
open Required		`boolean` Determines whether the overlay portion of the component should be shown or not
anchorId		`string` An override to the internal id that will be spread on to the renderAnchor
anchorRef		`RefObject<HTMLElement>` An override to the internal renderAnchor ref that will be used to position the overlay. When renderAnchor is null this can be used to make an anchor that is detached from ActionMenu. An override to the internal ref that will be spread on to the renderAnchor
onSelectedChange Required		`(selected: ItemInput \| ItemInput[]) => void` Provide a callback called when the selected item(s) change
onFilterChange		`(value: string, e: ChangeEvent<HTMLInputElement>) => void` Callback when the search input changes
onCancel		`() => void` (Narrow screens) Callback when the user hits cancel or close
overlayProps		`Partial<OverlayProps>` See Overlay props.
textInputProps		`Partial<Omit<TextInputProps, 'onChange'>>` See TextInput props.
footer	`null`	`string \| React.ReactElement` Footer rendered at the end of the panel