Select

Choose an option from a predefined list, displayed in a dropdown

The Select component is an extended List component. Any prop that the List component can accept, can also be used by the Select component. To better understand how this component works, we recommend reading through the documentation of the List component first.

---
import { Select } from 'webcoreui/astro'
---

<Select
    name="select-id"
    itemGroups={[...]}
    showSearchBar={true}
    showSearchBarIcon={true}
    searchBarPlaceholder="Filter options"
/>

<script>
    import { listen } from 'webcoreui'

    listen('selectOnChange', event => console.log(event))
    listen('selectOnClose', event => console.log(event))
</script>

<script>
    import { Select } from 'webcoreui/svelte'
</script>

<Select
    name="select-id"
    itemGroups={[...]}
    showSearchBar={true}
    showSearchBarIcon={true}
    searchBarPlaceholder="Filter options"
    onChange={event => console.log(event)}
    onClose={event => console.log(event)}
/>

import React from 'react'
import { Select } from 'webcoreui/react'

const Component = () => (
    <Select
        name="select-id"
        itemGroups={[...]}
        showSearchBar={true}
        showSearchBarIcon={true}
        searchBarPlaceholder="Filter options"
        onChange={event => console.log(event)}
        onClose={event => console.log(event)}
    />
)

export default Component

To handle select events, listen to the selectOnChange event in Astro, or use the onChange prop for Svelte and React components. The event object returns the following properties:

{
    select: 'select-id'     // The name prop of the Select component
    value: 'new',           // Value of the clicked item
    name: 'Create issue',   // Name of the clicked item
    list: ul._list_1rduk_1  // HTMLUListElement - the ul which the item belongs to
}

You can also listen to the selectOnClose event in Astro, or use the onClose prop for svelte and React components to determine when the select is closed without a selection, for example when it loses focus or closed with the Esc key.

States

The select event is only triggered for active Select components. To disable a Select component, set the disabled prop to true:

<Select
    name="select-id"
    itemGroups={[...]}
    disabled={true}
    showSearchBar={true}
    showSearchBarIcon={true}
    searchBarPlaceholder="Filter options"
/>

For default values, you can use the value prop. You can either set an arbitrary value, or use one of the values from your itemsGroups prop:

<Select
    name="select-id"
    value="Arbitrary value"
    itemGroups={[...]}
    updateValue={false}
    showSearchBar={true}
    showSearchBarIcon={true}
    searchBarPlaceholder="Filter options"
/>

<Select
    name="select-id"
    value="new"
    itemGroups={[{
        title: 'Suggestions',
        items: [
            {
                name: 'Create issue',
                value: 'new',
                ...
            },
            { ... },
            { ... }
        ]
    }, { ... }]}
    updateValue={false}
    showSearchBar={true}
    showSearchBarIcon={true}
    searchBarPlaceholder="Filter options"
/>

If you’d like to use the Select component as a command list or as a combobox, you can disable automatic value update to keep its placeholder/value intact using the updateValue prop:

<Select
    name="select-id"
    itemGroups={[...]}
    value="Take an action"
    updateValue={false}
    showSearchBar={true}
    showSearchBarIcon={true}
    searchBarPlaceholder="Filter options"
/>

Labels

The Select component can be labelled in three different ways using the following props:

• label: Sets a label above the input field.
• placeholder: Sets a label inside the input field.
• subText: Sets a label below the input field.

<Select
    name="select-id"
    label="Commonly used actions"
    itemGroups={[...]}
    showSearchBar={true}
    showSearchBarIcon={true}
    searchBarPlaceholder="Filter options"
/>

<Select
    name="select-id"
    placeholder="Commonly used actions"
    itemGroups={[...]}
    showSearchBar={true}
    showSearchBarIcon={true}
    searchBarPlaceholder="Filter options"
/>

<Select
    name="select-id"
    subText="Take an action or jump to a page"
    itemGroups={[...]}
    showSearchBar={true}
    showSearchBarIcon={true}
    searchBarPlaceholder="Filter options"
/>

Positioning

By default, options are displayed under the Select component. These options can be repositioned using the position prop. Please see the API documentation below for all possible position values. The following three Select components demonstrate the left, right, and modal positions.

API

type SelectProps = {
    name: string
    value?: string
    placeholder?: string
    label?: string
    subText?: string
    disabled?: boolean
    updateValue?: boolean
    position?: 'top'
    | 'bottom'
    | 'left'
    | 'left-start'
    | 'left-end'
    | 'right'
    | 'right-start'
    | 'right-end'
    | 'modal'
} & ListProps

type SvelteSelectProps = {
    onChange?: (event: ListEventType & { select: string }) => void
    onClose?: (event: ModalCallback | PopoverCallback) => void
} & SelectProps

type ReactSelectProps = {
    onChange?: (event: ListEventType & { select: string }) => void
    onClose?: (event: ModalCallback | PopoverCallback) => void
} & SelectProps