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

ready

Storybook|Source

Rails

ready

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()),
  )
  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={filteredItems}
        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()),
  )
  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={filteredItems}
        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()),
  )
  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={filteredItems}
        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()),
  )
  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={filteredItems}
        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()),
  )
  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={filteredItems}
        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()),
  )
  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={filteredItems}
        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()),
  )
  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={filteredItems}
        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()),
  )
  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={filteredItems}
        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()),
  )


  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={filteredItems}
        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()),
  )

  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={filteredItems}
        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()),
  )


  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={filteredItems}
        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()),
  )

  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={filteredItems}
        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()),
  )
  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={filteredItems}
        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()),
  )
  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={filteredItems}
        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()),
  )
  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={filteredItems}
      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()),
  )
  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={filteredItems}
      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()),
  )


  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={filteredItems}
        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()),
  )

  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={filteredItems}
        selected={selected}
        onSelectedChange={setSelected}
        onFilterChange={setFilter}
      />
    </FormControl>
  )
}

Internal label

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 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()),
  )
  const [open, setOpen] = React.useState(false)


  return (
    <SelectPanel
      renderAnchor={({children, ...anchorProps}) => (
        <Button {...anchorProps} trailingAction={TriangleDownIcon} aria-haspopup="dialog">
          <span
            style={{
              color: 'var(--fgColor-muted)',
              display: 'inline-block',
            }}
          >
            Choices:
          </span>{' '}
          {children || 'None selected'}
        </Button>
      )}
      placeholder="Pick choices"
      open={open}
      onOpenChange={setOpen}
      items={filteredItems}
      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 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()),
  )
  const [open, setOpen] = React.useState(false)

  return (
    <SelectPanel
      renderAnchor={({children, ...anchorProps}) => (
        <Button {...anchorProps} trailingAction={TriangleDownIcon} aria-haspopup="dialog">
          <span
            style={{
              color: 'var(--fgColor-muted)',
              display: 'inline-block',
            }}
          >
            Choices:
          </span>{' '}
          {children || 'None selected'}
        </Button>
      )}
      placeholder="Pick choices"
      open={open}
      onOpenChange={setOpen}
      items={filteredItems}
      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()),
  )


  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={filteredItems}
        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()),
  )

  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={filteredItems}
        selected={selected}
        onSelectedChange={setSelected}
        onFilterChange={setFilter}
      />
    </FormControl>
  )
}

Empty State Message

If no message prop is supplied, a generic default empty state message "No items available" will be automatically used. To ensure that this message is congruent with your SelectPanel implementation, manually configure a custom empty state message. Currently, the default message is displayed both when the SelectPanel is completely empty (no items at all), as well as when no results are found while filtering. You may choose to use conditional logic if necessary to control when your custom empty message will appear, or to display different messages for each empty scenario.

...
<SelectPanel message={
    items.length === 0
      ? {
          title: "You haven't created any items yet",
          variant: "empty",
          body: "Please add or create new items to populate the list.",
        }
      : undefined
  } ...
/>

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' \| 'cancel' ) => 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 and variant=modal) Callback when the user hits cancel or close
overlayProps		`Partial<OverlayProps>` See Overlay props.
textInputProps		`Partial<Omit<TextInputProps, 'onChange'>>` See TextInput props.
variant	`'anchored'`	`'anchored' \| 'modal'` Anchored by default, SelectPanel can be opened as a modal
footer Deprecated	`null`	`string \| React.ReactElement` Please use `secondaryAction` instead.
message	`A default empty message is provided if this option is not configured. Supply a custom empty message to override the default.`	`{title: string \| React.ReactElement; variant: 'empty' \| 'error' \| 'warning'; body: React.ReactNode; icon?:React.ComponentType<IconProps>;action?: React.ReactElement;}` Message to display in the panel in case of error or empty results
notice		`{text: string \| React.ReactElement; variant: 'empty' \| 'error' \| 'warning';}` Optional notice to display on top of the panel
secondaryAction	`null`	`React.ReactElement` Secondary action, it will be rendered in the footer of the panel. Use `SecondaryActionButton` or `SecondaryActionLink` for the action.
showSelectedOptionsFirst		`boolean` Whether to display the selected items at the top of the list
showSelectAll	`false`	`boolean` When `true` and on a multi-select SelectPanel, displays a 'Select all' checkbox that allows users to select or deselect all visible items at once. The checkbox label automatically toggles between 'Select all' and 'Deselect all' based on the current selection state, and shows an indeterminate state when some items are selected.
disableFullscreenOnNarrow	`undefined (uses feature flag default)`	`boolean` Whether to disable fullscreen behavior on narrow viewports. When `true`, the panel will maintain its anchored position regardless of viewport size. When `false`, the panel will go fullscreen on narrow viewports (if feature flag is enabled).
loading	`false`	`boolean` Whether the panel is in a loading state. When `true`, the panel will display a loading spinner. If `loading` is not provided, the panel will infer the loading state based on the contents of `items` available.
align	`'start'`	`'start' \| 'end' \| 'center'` Determines the alignment of the panel relative to the anchor. Defaults to 'start' which aligns the left edge of the panel with the left edge of the anchor.