Select

The Select component provides a way to create dropdown selections with various sub-components for customization.

Usage

import { Select } from '@harnessio/ui/components'

//...

const [color, setColor] = useState()

return (
  <Select.Root
    name="color"
    placeholder="Select..."
    label="Color theme"
    value={color}
    onValueChange={setColor}
  >
    <Select.Content>
      <Select.Item value="standard">Standard</Select.Item>
      <Select.Item value="accessible">Accessible</Select.Item>
      <Select.Item value="vivid">Vivid</Select.Item>

      <Select.Separator />

      <Select.Group>
        <Select.Label>Custom label</Select.Label>
        <Select.Item value="custom">Custom</Select.Item>
      </Select.Group>
    </Select.Content>
  </Select.Root>
)

Anatomy

All parts of the Select component can be imported and composed as required.

<Select.Root>
  <Select.Content>
    <Select.Item />
    <Select.Separator />
    <Select.Group>
      <Select.Label />
      <Select.Item />
    </Select.Group>
  </Select.Content>
</Select.Root>

API Reference

Root

The Root component for the Select can be either controlled or uncontrolled. A controlled Select component takes a value and an onValueChange handler as props, and will only update the value when the user makes a selection. An uncontrolled Select component will update the value whenever a user makes a selection, and will not re-render when the value is changed from outside the component.

<Select.Root
  name="color"                        // [OPTIONAL] Name of the select
  label="Color theme"                 // [OPTIONAL] Label text
  placeholder="Select a color theme"  // [OPTIONAL] Placeholder text
  value={color}                       // [OPTIONAL] Current value
  onValueChange={setColor}            // [OPTIONAL] Value change handler
>
  {/* Select content */}
</Select.Root>

Prop	Required	Default	Type
name	false		string
label	false		string
placeholder	false		string
value	false		string
onValueChange	false		(value: string) => void

Content

The content of the select dropdown. This is a required element. The defaultValue prop sets the default value of the select. The withSearch prop enables search support in the dropdown. This is optional and can be used to search the available options. The searchProps prop is used to pass additional props to the search input when withSearch is true. This can be used to customize the search input, such as changing the placeholder text.

<Select.Content
  defaultValue={color}                 // [OPTIONAL] Default value
  className="custom-class"             // [OPTIONAL] Custom class name
  position="popper"                    // [OPTIONAL] Position of the content, either 'item-aligned' or 'popper'
  withSearch                           // [OPTIONAL] Enable search
  searchProps={{                       // [OPTIONAL] Search props
    placeholder: 'Search...',          // [OPTIONAL] Placeholder text
    searchValue: search,               // [OPTIONAL] Current search value
    handleChangeSearchValue: setSearch // [OPTIONAL] Search value change handler
  }}
>
  {/* SelectItem components */}
</Select.Content>

Prop	Required	Default	Type
defaultValue	false		string
className	false		string
position	false	popper	'item-aligned' | 'popper'
withSearch	false	false	boolean
searchProps	false		{ placeholder?: string, searchValue: string, handleChangeSearchValue: (searchValue: string) => void }

Item

The Item component is used to create an individual item in the select dropdown. Each item requires a value prop which is the value of the item. If the value is not suitable for typeahead search, you can use the textValue prop to provide a searchable text string for typeahead search. For example, if the value is JSON-encoded object, textValue can be used to provide a searchable label for the object.

<Select.Item
  value="value"     // Value of the item
  textValue="text"  // [OPTIONAL] Text value of the item to be used for when value suitable for typeahead search
  disabled          // [OPTIONAL] Disable the item
  asChild           // [OPTIONAL] Render the item as a child
  isItemTextAsChild // [OPTIONAL] Render the item text as a child
>
  Name
</Select.Item>

Prop	Required	Default	Type
value	true		string
textValue	false		string
disabled	false	false	boolean
asChild	false	false	boolean
isItemTextAsChild	false	false	boolean

Separator

The Separator component is used to create a separator in the select dropdown.

<Select.Separator
  className="custom-class" // [OPTIONAL] Custom class name
/>

Prop	Required	Default	Type
className	false		string

Group

The Group component is used to create a group of items in the select dropdown.

<Select.Group
  className="custom-class" // [OPTIONAL] Custom class name
>
  <Select.Label>Custom label</Select.Label>
  <Select.Item value="custom">Custom</Select.Item>
</Select.Group>

Prop	Required	Default	Type
className	false		string

Label

The Label component is used to create a label for a group of items in the select dropdown.

<Select.Label
  className="custom-class" // [OPTIONAL] Custom class name
>
  Custom label
</Select.Label>

Prop	Required	Default	Type
className	false		string