@primer/components 32.0.0 → 32.0.2-rc.859381a1

package/docs/content/Portal.mdx

@@ -0,0 +1,78 @@
+---
+title: Portal
+---
+
+Portals allow you to create a separation between the logical React component hierarchy and the physical DOM. See the [React documentation on portals](https://reactjs.org/docs/portals.html) for an in-depth explanation.
+
+This Portal component will render all children into the portal root DOM node instead of as children of this Portal's parent DOM element. This is useful for breaking out of the current stacking context. For example, popup menus and tooltips may need to render on top of (read: covering up) other UI. The best way to guarantee this is to add these elements to top-level DOM, such as directly on `document.body`. These elements can then be moved to the correct location using absolute positioning.
+
+## Customizing the portal root
+
+By default, Primer will create a portal root for you as a child of the closest `<BaseStyles>` element, or `document.body` if none is found. That root will be positioned absolutely in the top-left corner of its parent element. If you would like to specify your own portal root, there are two options:
+
+1. Before rendering a `<Portal>` for the first time, ensure that an element exists with id `__primerPortalRoot__`. If that exists, it will be used as the default portal root.
+2. Call the `registerPortalRoot` function, passing in the element you would like to use as your default portal root.
+
+Keep in mind that any inherited styles applied to portaled elements are based on its physical DOM parent. Practically this means that styles added by a `<BaseStyles>` element will not apply to the portaled content unless the portal root is a descendent of a `<BaseStyles>` element.
+
+Also, as `<ThemeProvider>` affects the _React_ context, which applies to the logical React component hierarchy, the portal root is not required to be a child of a `<ThemeProvider>` for its children to receive that context.
+
+## Multiple portal roots
+
+There may be situations where you want to have multiple portal roots. Advanced scenarios may necessitate multiple stacking contexts for overlays. You can set up multiple roots using the `registerPortalRoot` function. Calling this function with an element and a string `name` will register the root, which can then be used by creating a `<Portal>` with a `name` prop matching the one you registered.
+
+## Default example
+
+```jsx
+<Portal>
+  Regardless of where this appears in the React component tree, this text will be rendered in the DOM within the portal
+  root at document.body.
+</Portal>
+```
+
+## Example: custom portal root
+
+```html
+<!-- Wherever in your DOM tree you would like to have the default portal root -->
+<div id="__primerPortalRoot__"></div>
+```
+
+or
+
+```js
+import { registerPortalRoot } from "@primer/components"
+registerPortalRoot(document.querySelector(".my-portal-root")!)
+```
+
+## Example: multiple portal roots
+
+```jsx
+import { Portal, registerPortalRoot } from "@primer/components"
+
+registerPortalRoot(document.querySelector(".scrolling-canvas-root")!, "scrolling-canvas")
+
+// ...
+
+export default () => (
+    <Portal containerName="scrolling-canvas">
+        <div>This div will be rendered into the element registered above.</div>
+        <Portal>
+            <div>
+                This div will be rendered into the default
+                portal root created at document.body
+            </div>
+        </Portal>
+    </Portal>
+)
+```
+
+## System props
+
+Since Portals do not render UI on their own, they do not accept any system props.
+
+## Component props
+
+| Name          | Type       | Default | Description                                                                                                                                    |
+| :------------ | :--------- | :-----: | :--------------------------------------------------------------------------------------------------------------------------------------------- |
+| onMount       | () => void |         | Called when this portal is added to the DOM                                                                                                    |
+| containerName | string     |         | Renders the portal children into the container registered with the given name. If omitted, children are rendered into the default portal root. |

package/docs/content/Position.md

@@ -0,0 +1,100 @@
+---
+title: Position Components
+status: Deprecated
+---
+
+The Position component is a wrapper component that gives the containing component css positioning abilities.
+
+## Deprecation
+
+Use [Box](/Box) instead.
+
+**Before**
+
+```jsx
+<>
+  <Position position="absolute">...</Position>
+  <Absolute>...</Absolute>
+  <Relative>...</Relative>
+  <Fixed>...</Fixed>
+  <Sticky>...</Sticky>
+</>
+```
+
+**After**
+
+```jsx
+<>
+  <Box position="absolute">...</Box>
+  <Box position="absolute">...</Box>
+  <Box position="relative">...</Box>
+  <Box position="fixed">...</Box>
+  <Box position="sticky">...</Box>
+</>
+```
+
+## Default examples
+
+```jsx live
+<Box p={2} mb={200}>
+  <Heading mb={2}>Relative + Absolute</Heading>
+  <Relative size={128} mx={128} my={6}>
+    <Box borderWidth="1px" borderStyle="solid" borderColor="border.default" borderRadius={2} size="100%">
+      <Absolute left="100%" top={0} color="fg.onEmphasis" bg="success.emphasis" p={1}>
+        rt
+      </Absolute>
+      <Absolute right="100%" top={0} color="fg.onEmphasis" bg="success.emphasis" p={1}>
+        lt
+      </Absolute>
+      <Absolute left="100%" bottom={0} color="fg.onEmphasis" bg="success.emphasis" p={1}>
+        rb
+      </Absolute>
+      <Absolute right="100%" bottom={0} color="fg.onEmphasis" bg="success.emphasis" p={1}>
+        lb
+      </Absolute>
+      <Absolute left={0} top="100%" color="fg.onEmphasis" bg="success.emphasis" p={1}>
+        bl
+      </Absolute>
+      <Absolute right={0} top="100%" color="fg.onEmphasis" bg="success.emphasis" p={1}>
+        br
+      </Absolute>
+      <Absolute left={0} bottom="100%" color="fg.onEmphasis" bg="success.emphasis" p={1}>
+        tl
+      </Absolute>
+      <Absolute right={0} bottom="100%" color="fg.onEmphasis" bg="success.emphasis" p={1}>
+        tr
+      </Absolute>
+    </Box>
+  </Relative>
+
+  <Heading my={2}>Sticky</Heading>
+
+  <Box
+    borderWidth="1px"
+    borderStyle="solid"
+    borderColor="success.emphasis"
+    borderRadius={2}
+    border={1}
+    height={500}
+  >
+    <Sticky top={0} bg="success.subtle" p={6}>
+      I'm sticky!
+    </Sticky>
+  </Box>
+
+  <Heading my={2}>Fixed</Heading>
+  <p>(see the bottom right of the screen)</p>
+
+  <Fixed bottom={0} right={0} color="fg.onEmphasis" bg="danger.emphasis" p={2}>
+    I'm fixed to the bottom right.
+  </Fixed>
+</Box>
+```
+
+## System props
+
+Position components get `POSITION`, `LAYOUT`, `FLEX`, and `COMMON` system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+## Component props
+
+Position does not get any additional props other than the system props mentioned above.

package/docs/content/ProgressBar.mdx

@@ -0,0 +1,29 @@
+---
+title: ProgressBar
+componentId: progress_bar
+source: https://github.com/primer/react/blob/main/src/ProgressBar.tsx
+---
+
+## Default example
+
+```jsx live
+<ProgressBar progress={80} />
+```
+
+If you'd like to use ProgressBar inline, pass the `inline` boolean prop & **be sure to set a width**.
+
+```jsx live
+<>
+  <Text mr={3}>5 of 10</Text>
+  <ProgressBar progress={50} inline sx={{width: '100px'}} />
+</>
+```
+
+## Component props
+
+| Name     | Type    |       Default       | Description                                                                                                                      |
+| :------- | :------ | :-----------------: | :------------------------------------------------------------------------------------------------------------------------------- |
+| progress | Number  |                     | Used to set the size of the green bar                                                                                            |
+| barSize  | String  |      'default'      | Controls the height of the progress bar. Can be 'small', 'large', or 'default'. If omitted, height is set to the default height. |
+| inline   | Boolean |        false        | Styles the progress bar inline                                                                                                   |
+| bg       | String  | 'bg.successInverse' | Set the progress bar color, defaults to bg-green                                                                                 |

package/docs/content/SelectMenu.md

@@ -0,0 +1,371 @@
+---
+title: SelectMenu
+---
+
+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
+
+```jsx live
+<SelectMenu>
+  <Button as="summary">Projects</Button>
+  <SelectMenu.Modal>
+    <SelectMenu.Header>Projects</SelectMenu.Header>
+    <SelectMenu.List>
+      <SelectMenu.Item href="#">Primer React bugs</SelectMenu.Item>
+      <SelectMenu.Item href="#">Primer React roadmap</SelectMenu.Item>
+      <SelectMenu.Item href="#"> Project 3</SelectMenu.Item>
+      <SelectMenu.Item href="#">Project 4</SelectMenu.Item>
+    </SelectMenu.List>
+  </SelectMenu.Modal>
+</SelectMenu>
+```
+
+## SelectMenu
+
+Main wrapper component for select menu.
+
+```jsx
+<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](https://reactjs.org/docs/context.html#reactcreatecontext) that exposes some helpful state values to be used via [`React.useContext`](https://reactjs.org/docs/hooks-reference.html#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](https://reactjs.org/docs/context.html#contextprovider).
+
+### 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
+
+```jsx
+import {SelectMenu, Button} from `@primer/components`
+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`.
+
+```jsx
+<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.
+
+```jsx live
+<Box position="relative" display="flex" justifyContent="flex-end">
+  <SelectMenu>
+    <Button as="summary">Projects</Button>
+    <SelectMenu.Modal align="right">
+      <SelectMenu.Header>Projects</SelectMenu.Header>
+      <SelectMenu.List>
+        <SelectMenu.Item href="#">Primer React bugs</SelectMenu.Item>
+        <SelectMenu.Item href="#">Primer React roadmap</SelectMenu.Item>
+        <SelectMenu.Item href="#"> Project 3</SelectMenu.Item>
+        <SelectMenu.Item href="#">Project 4</SelectMenu.Item>
+      </SelectMenu.List>
+    </SelectMenu.Modal>
+  </SelectMenu>
+</Box>
+```
+
+### 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 accessbility 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.
+
+```jsx
+<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](/core-concepts#the-as-prop). Be sure to consider [which HTML element is the right choice](https://marcysutton.com/links-vs-buttons-in-modern-web-applications) for your usage of the component.
+
+```jsx
+<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.
+
+```jsx live
+<SelectMenu>
+  <Button as="summary">Projects</Button>
+  <SelectMenu.Modal>
+    <SelectMenu.Header>Filter by Project</SelectMenu.Header>
+    <SelectMenu.Filter placeholder="Filter projects" value="" aria-label="Filter Projects" />
+    <SelectMenu.List>
+      <SelectMenu.Item href="#">Primer React bugs</SelectMenu.Item>
+      <SelectMenu.Item href="#">Primer React roadmap</SelectMenu.Item>
+      <SelectMenu.Divider>More Options</SelectMenu.Divider>
+      <SelectMenu.Item href="#"> Project 3</SelectMenu.Item>
+      <SelectMenu.Item href="#">Project 4</SelectMenu.Item>
+    </SelectMenu.List>
+  </SelectMenu.Modal>
+</SelectMenu>
+```
+
+### Component Props
+
+SelectMenu.Filter components receive all the props that the [TextInput](/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 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`.
+
+```jsx live
+<SelectMenu>
+  <Button as="summary">Projects</Button>
+  <SelectMenu.Modal>
+    <SelectMenu.Header>Projects</SelectMenu.Header>
+    <SelectMenu.Tabs>
+      <SelectMenu.Tab index={0} tabName="Repository" />
+      <SelectMenu.Tab index={1} tabName="Organization" />
+    </SelectMenu.Tabs>
+    <SelectMenu.TabPanel tabName="Repository">
+      <SelectMenu.Item href="#">Primer React bugs</SelectMenu.Item>
+      <SelectMenu.Item href="#">Primer React roadmap</SelectMenu.Item>
+      <SelectMenu.Item href="#"> Project 3</SelectMenu.Item>
+      <SelectMenu.Item href="#">Project 4</SelectMenu.Item>
+    </SelectMenu.TabPanel>
+    <SelectMenu.TabPanel tabName="Organization">
+      <SelectMenu.Item href="#"> Project 2</SelectMenu.Item>
+    </SelectMenu.TabPanel>
+    <SelectMenu.Footer>Showing 3 of 3</SelectMenu.Footer>
+  </SelectMenu.Modal>
+</SelectMenu>
+```
+
+### 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.
+
+```jsx
+<>
+  <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.
+
+```jsx
+<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`.
+
+```jsx live
+<SelectMenu>
+  <Button as="summary">Projects</Button>
+  <SelectMenu.Modal>
+    <SelectMenu.Header>Projects</SelectMenu.Header>
+    <SelectMenu.List>
+      <SelectMenu.Item href="#">Primer React bugs</SelectMenu.Item>
+      <SelectMenu.Item href="#">Primer React roadmap</SelectMenu.Item>
+      <SelectMenu.Divider>More Options</SelectMenu.Divider>
+      <SelectMenu.Item href="#"> Project 3</SelectMenu.Item>
+      <SelectMenu.Item href="#">Project 4</SelectMenu.Item>
+    </SelectMenu.List>
+  </SelectMenu.Modal>
+</SelectMenu>
+```
+
+### 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.
+
+```jsx live
+<SelectMenu>
+  <Button as="summary">Projects</Button>
+  <SelectMenu.Modal>
+    <SelectMenu.Header>Projects</SelectMenu.Header>
+    <SelectMenu.List>
+      <SelectMenu.Item href="#">Primer React bugs</SelectMenu.Item>
+      <SelectMenu.Item href="#">Primer React roadmap</SelectMenu.Item>
+      <SelectMenu.Item href="#"> Project 3</SelectMenu.Item>
+      <SelectMenu.Item href="#">Project 4</SelectMenu.Item>
+      <SelectMenu.Footer>Use ⌥ + click/return to exclude labels.</SelectMenu.Footer>
+    </SelectMenu.List>
+  </SelectMenu.Modal>
+</SelectMenu>
+```
+
+### 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.
+
+```jsx live
+<SelectMenu>
+  <Button as="summary">Projects</Button>
+  <SelectMenu.Modal>
+    <SelectMenu.Header>Projects</SelectMenu.Header>
+    <SelectMenu.List>
+      <SelectMenu.Item href="#">Primer React bugs</SelectMenu.Item>
+      <SelectMenu.Item href="#">Primer React roadmap</SelectMenu.Item>
+      <SelectMenu.Item href="#"> Project 3</SelectMenu.Item>
+      <SelectMenu.Item href="#">Project 4</SelectMenu.Item>
+      <SelectMenu.Footer>Use ⌥ + click/return to exclude labels.</SelectMenu.Footer>
+    </SelectMenu.List>
+  </SelectMenu.Modal>
+</SelectMenu>
+```
+
+### 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.
+
+```jsx live
+<SelectMenu>
+  <Button as="summary">Projects</Button>
+  <SelectMenu.Modal>
+    <SelectMenu.Header>Projects</SelectMenu.Header>
+    <SelectMenu.Filter placeholder="Filter projects" value="" aria-label="Filter Projects" />
+    {true ? (
+      <SelectMenu.LoadingAnimation />
+    ) : (
+      <SelectMenu.List>
+        <SelectMenu.Item href="#">Primer React bugs</SelectMenu.Item>
+        <SelectMenu.Item href="#">Primer React roadmap</SelectMenu.Item>
+        <SelectMenu.Item href="#"> Project 3</SelectMenu.Item>
+        <SelectMenu.Item href="#">Project 4</SelectMenu.Item>
+        <SelectMenu.Footer>Use ⌥ + click/return to exclude labels.</SelectMenu.Footer>
+      </SelectMenu.List>
+    )}
+  </SelectMenu.Modal>
+</SelectMenu>
+```
+
+### Component Props
+
+| Name | Type              | Default | Description                          |
+| :--- | :---------------- | :-----: | :----------------------------------- |
+| sx   | SystemStyleObject |   {}    | Style to be applied to the component |

package/docs/content/SelectPanel.mdx

@@ -0,0 +1,67 @@
+---
+title: SelectPanel
+status: Alpha
+---
+
+A `SelectPanel` provides an anchor that will open an overlay with a list of selectable items, and a text input to filter the selectable items
+
+## Example
+
+```javascript live noinline
+function getColorCircle(color) {
+  return function () {
+    return (
+      <Box
+        borderWidth="1px"
+        borderStyle="solid"
+        bg={color}
+        borderColor={color}
+        width={14}
+        height={14}
+        borderRadius={10}
+        margin="auto"
+      />
+    )
+  }
+}
+
+const items = [
+  {leadingVisual: getColorCircle('#a2eeef'), text: 'enhancement', id: 1},
+  {leadingVisual: getColorCircle('#d73a4a'), text: 'bug', id: 2},
+  {leadingVisual: getColorCircle('#0cf478'), text: 'good first issue', id: 3},
+  {leadingVisual: getColorCircle('#ffd78e'), text: 'design', id: 4},
+  {leadingVisual: getColorCircle('#ff0000'), text: 'blocker', id: 5},
+  {leadingVisual: getColorCircle('#a4f287'), text: 'backend', id: 6},
+  {leadingVisual: getColorCircle('#8dc6fc'), text: 'frontend', id: 7}
+]
+
+function DemoComponent() {
+  const [selected, setSelected] = React.useState([items[0], items[1]])
+  const [filter, setFilter] = React.useState('')
+  const filteredItems = items.filter(item => item.text.toLowerCase().startsWith(filter.toLowerCase()))
+  const [open, setOpen] = React.useState(false)
+
+  return (
+    <SelectPanel
+      renderAnchor={({children, 'aria-labelledby': ariaLabelledBy, ...anchorProps}) => (
+        <DropdownButton aria-labelledby={` ${ariaLabelledBy}`} {...anchorProps}>
+          {children || 'Select Labels'}
+        </DropdownButton>
+      )}
+      placeholderText="Filter Labels"
+      open={open}
+      onOpenChange={setOpen}
+      items={filteredItems}
+      selected={selected}
+      onSelectedChange={setSelected}
+      onFilterChange={setFilter}
+      showItemDividers={true}
+      overlayProps={{width: 'small', height: 'xsmall'}}
+    />
+  )
+}
+
+render(<DemoComponent />)
+```
+
+## Component props