Select

The Select component is a controlled component that can be used to select one option from a set. It can be used in a group with other selects to allow for multiple selections.

import {
  Select,
  Option,
  OptionGroup,
  OptionGroupLabel,
  createSelectCollection
} from '@cerberus/react'

Usage

The Select component is a controlled component that can be used to select one option from a set. It can be used in a group with other selects to allow for multiple selections.

Select Relative

import {
  For,
  Field,
  Select,
  Option,
  createSelectCollection
} from '@cerberus/react'
import { Box } from 'styled-system/jsx'

function SelectBasicPreview() {
  const collection = createSelectCollection([
    { label: 'Hades', value: 'hades' },
    { label: 'Persephone', value: 'persephone' },
    { label: 'Zeus', value: 'zeus', disabled: true },
    { label: 'Poseidon', value: 'poseidon' },
    { label: 'Hera', value: 'hera' },
  ])

  return (
    <Box w="1/2">
      <Field label="Select Relative">
        <Select collection={collection} placeholder="Choose option">
          <For each={collection.items}>
            {(item) => <Option key={item.value} item={item} />}
          </For>
        </Select>
      </Field>
    </Box>
  )
}

Grouped Options

To group options, use the OptionGroup and OptionGroupLabel components.

Select Relative

import {
  For,
  Field,
  Select,
  Option,
  OptionGroup,
  OptionGroupLabel,
  createSelectCollection
} from '@cerberus/react'
import { Box } from 'styled-system/jsx'

function GroupedOptionsDemo() {
  const collection = createSelectCollection([
    { label: 'Hades', value: '1-hades' },
    { label: 'Persephone', value: '1-persephone' },
    { label: 'Zeus', value: '1-zeus', disabled: true },
    { label: 'Poseidon', value: '1-poseidon' },
    { label: 'Hera', value: '1-hera' },
  ])

  return (
    <Box w="1/2">
      <Field label="Select Relative">
        <Select collection={collection} placeholder="Choose option">
          <OptionGroup>
            <OptionGroupLabel>The fam</OptionGroupLabel>
            <For each={collection.items}>
              {(item) => <Option key={item.value} item={item} />}
            </For>
          </OptionGroup>
        </Select>
      </Field>
    </Box>
  )
}

With Dialog

'use client'

import {
  Dialog,
  DialogCloseIconTrigger,
  DialogDescription,
  DialogHeading,
  DialogProvider,
  DialogTrigger,
} from '@cerberus/react'
import { Box, VStack } from 'styled-system/jsx'
import { SelectBasicPreview } from './select-preview'

export function SelectWithDialogDemo() {
  return (
    <DialogProvider>
      <DialogTrigger>Open Select Dialog</DialogTrigger>
      <Dialog>
        <VStack alignItems="flex-start" gap="lg" w="full">
          <DialogCloseIconTrigger />
          <DialogHeading>Some heading</DialogHeading>
          <DialogDescription>
            This is a description for the dialog. You can use this space to
            provide more context or instructions for the user.
          </DialogDescription>

          <Box w="full">
            <SelectBasicPreview />
          </Box>
        </VStack>
      </Dialog>
    </DialogProvider>
  )
}

Primitives

You can utilize the primitive components or the css prop to customize the select.

Component	Description
SelectRoot	The context provider for the Select family
SelectLabel	The label that appears above the select input
SelectControl	The wrapper to the select trigger that opens the dropdown
SelectTrigger	he trigger that opens the dropdown
SelectValueText	The text that appears in the trigger
SelectIndicator	The indicator that appears in the trigger
SelectClearTrigger	The trigger that clears the selected value
SelectPositioner	The wrapper that positions the dropdown
SelectContent	The content of the dropdown (i.e. the container itself)
SelectItemGroup	The group of options in the dropdown
SelectItemGroupLabel	The label for the group of options
SelectItem	The option in the dropdown
SelectItemText	The text label of the option
SelectItemIndicator	The indicator shown when the option is selected
SelectHiddenInput	The native select for the select group.

Select a custom relative

function SelectCustomPreview() {
  const collection = createSelectCollection([
    { label: 'Hades', value: '1-hades' },
    { label: 'Persephone', value: '1-persephone' },
    { label: 'Zeus', value: '1-zeus', disabled: true },
    { label: 'Poseidon', value: '1-poseidon' },
    { label: 'Hera', value: '1-hera' },
  ])

  return (
    <Box w="1/2">
      <SelectParts.Root collection={collection}>
        <SelectParts.Label
          css={{
            paddingBlock: 2,
            textStyle: 'body-sm',
            textTransform: 'uppercase',
          }}
        >
          Select a custom relative
        </SelectParts.Label>

        <SelectParts.Control>
          <SelectParts.Trigger
            className={cx(
              css({
                bgColor: 'black',
                color: 'danger.surface.initial',
                paddingInline: 4,
                paddingBlock: 3,
                _hover: {
                  bgColor: 'danger.surface.initial',
                  color: 'white',
                },
              }),
              hstack({
                justify: 'space-between',
                w: 'full',
              }),
            )}
          >
            <SelectParts.ValueText placeholder="Choose a custom option" />
            <SelectParts.Indicator
              css={{
                transitionProperty: 'transform',
                transitionDuration: 'fast',
                _open: {
                  transform: 'rotate(180deg)',
                },
              }}
            >
              <ChevronDownOutline />
            </SelectParts.Indicator>
          </SelectParts.Trigger>
          <SelectParts.ClearTrigger>Clear</SelectParts.ClearTrigger>
        </SelectParts.Control>

        <Portal>
          <SelectParts.Positioner css={{ w: 'var(--reference-width)' }}>
            <SelectParts.Content
              css={{
                bgColor: 'danger.surface.initial',
                p: 4,
              }}
            >
              <SelectParts.ItemGroup>
                <SelectParts.ItemGroupLabel
                  css={css({
                    fontWeight: 'bold',
                    textStyle: 'label-sm',
                    textTransform: 'uppercase',
                  })}
                >
                  The fam
                </SelectParts.ItemGroupLabel>

                <For each={collection.items}>
                  {(item, idx) => (
                    <SelectParts.Item key={item.value} item={item}>
                      <SelectParts.ItemText
                        css={{
                          color: 'white',
                          display: 'inline-block',
                        }}
                        style={{
                          paddingInlineStart: `calc(16px * ${idx})`,
                        }}
                      >
                        {item.label}
                      </SelectParts.ItemText>
                      <SelectParts.ItemIndicator>✓</SelectParts.ItemIndicator>
                    </SelectParts.Item>
                  )}
                </For>
              </SelectParts.ItemGroup>
            </SelectParts.Content>
          </SelectParts.Positioner>
        </Portal>
      </SelectParts.Root>
    </Box>
  )
}

API

Select

The Select component is an abstraction of our primitives and accepts the following props:

Name	Default	Description
placeholder		The placeholder to show in the select trigger.
size	'md'	The size of the select.
collection		The collection of options to show in the dropdown.

The Select component also accepts all the props of the SelectRoot primitive props

Option

The Option component is an abstraction of our primitives and accepts the following props:

Name	Default	Description
item		The item to show in the dropdown. `SelectCollectionItem`

The Option component also accepts all the props of the SelectItem primitive props

OptionGroup

The OptionGroup component is an abstraction of our primitives and accepts the same props as the SelectItemGroup primitive.

OptionGroupLabel

The OptionGroupLabel component is an abstraction of our primitives and accepts the same props as the SelectItemGroupLabel primitive.

createSelectCollection

The createSelectCollection function is a utility function that creates a collection of options for the Select component.

export function createSelectCollection(
  collection: SelectCollectionItem[],
): ListCollection<SelectCollectionItem> {
  return createListCollection({
    items: collection,
  })
}

Parts

The SelectParts API is an Object containing the full family of components.

Name	Description
Root	The `SelectRoot` component which is the Provider for the family.
Label	The `SelectLabel` component which displays the label and "required" notice.
Control	The `SelectControl` component which is the visual field.
Trigger	The `SelectTrigger` component which is the trigger for the dropdown.
ClearTrigger	The `SelectClearTrigger` component which is the trigger to clear the selected value.
ValueText	The `SelectValueText` component which displays the selected value.
Indicator	The `SelectIndicator` component which displays the trigger indicator.
Positioner	The `SelectPositioner` component which is controls the positioning for the dropdown.
Content	The `SelectContent` component which is the dropdown itself.
ItemGroup	The `SelectItemGroup` component which is the group of options in the dropdown.
ItemGroupLabel	The `SelectItemGroupLabel` component which is the label for the group of options.
Item	The `SelectItem` component which is the option in the dropdown.
ItemText	The `SelectItemText` component which is the text label of the option.
ItemIndicator	The `SelectItemIndicator` component which displays based on the `checked` state.
HiddenInput	The `SelectHiddenInput` component which displays the native input.

On this page

Edit this page on Github