Select

Description

Select provides a single-option select menu.

See live demos on storybook

Storybook Select Demos

Install from Artifactory

• Verify that you have access to (https://docs.int.bayer.com/cloud/devops/artifactory/)[Bayer Artifactory]
  • Verify your token is correctly set up in your .npmrc as per the link above
• Verify you have the @element scope configured in your .npmrc
  • @element:registry=https://artifactory.bayer.com/artifactory/api/npm/npm-platforms-engineering/
• Install the component and themes bundles
  • npm i @element/react-components @element/themes
    • alternatively install the component individually along with the themes bundle npm i @element/react-select @element/themes

Notes

There are two categories of the Select component, Select and Multi-Select. Select allows a user to choose one option from a list and Multi-Select allows a user to choose one or more options from a list.

Notable props for the Select component include clearable, which adds an Icon Button that allows users to clear their choice(s) in Select, and showSelectAll, which shows an option for the user to select all options from a list. Another important prop is requireConfirmation which is used with Multi-Select, requires a confirmation before the onChange will be called, and is required for the cancelLabel and confirmLabel props to be used.

Additionally, several combinations of styles and features exist for Select.

The Filled style of Select shows a textbox with a light gray background color behind the text, whereas the Outlined style of Select shows a textbox with no added background color but a solid line around it.

The Autocomplete feature fills in an option from the list based on characters input by the user and can be used with either style of Select.

Usage

The Select component can be used within many other components, like Menu, Card, and Modal, and is most commonly used in forms. Select can also include smaller components like Icons, as shown in the 'Options with Leading Icon' story.

Option Schema Examples

export const simpleArray = ['Cat', 'Dog', 'Ferret'];

export const options = [
    { displayName: 'Grains', value: 'grains' },
    { displayName: 'Vegetables', value: 'vegetables' },
    { displayName: 'Fruit', value: 'fruit' }
];

export const foodSchema = [
    {
        groupName: 'Carbs',
        id: 'carbs',
        options: [
            { text: 'Fries', value: 'fries' },
            { text: 'Bread', value: 'bread' }
        ]
    },
    {
        groupName: 'Dairy',
        id: 'dairy',
        options: [
            { text: 'Milk', value: 'milk' },
            { text: 'Cheese', value: 'cheese' }
        ]
    }
];

export const groupSchema = [
    {
        groupName: 'Chevy',
        id: 'chevy',
        options: [
            { text: 'Malibu', value: 'malibu' },
            { text: 'Suburban', value: 'suburban' }
        ]
    },
    {
        groupName: 'Ford',
        id: 'ford',
        options: [
            { text: 'Focus', value: 'focus' },
            {
                text: 'F-150',
                value: 'f150'
            }
        ]
    }
];

    const nestedOptions = [
        {
            id: 'cars',
            options: [
                {
                    groupName: 'Chevy',
                    id: 'chevy',
                    options: [
                        {
                            text: 'Malibu',
                            value: 'malibu'
                        },
                        {
                            text: 'Suburban',
                            value: 'suburban'
                        }
                    ]
                },
                {
                    groupName: 'Ford',
                    id: 'ford',
                    options: [
                        {
                            text: 'Focus',
                            value: 'focus'
                        },
                        {
                            text: 'F-150',
                            value: 'f150'
                        }
                    ]
                }
            ]
        }
        {
            id: 'food',
            options: [
                {
                    groupName: 'Carbs',
                    id: 'carbs',
                    options: [
                        {
                            text: 'Fries',
                            value: 'fries'
                        },
                        {
                            text: 'Bread',
                            value: 'bread'
                        }
                    ]
                },
                {
                    groupName: 'Dairy',
                    id: 'dairy',
                    options: [
                        {
                            text: 'Milk',
                            value: 'milk'
                        },
                        {
                            text: 'Cheese',
                            value: 'cheese'
                        }
                    ]
                }
            ]
        }
    ];

Testing

When unit testing the Select - unlike previous versions the menu is not rendered until visible. If you are testing for specific menu options, use defaultOpen so that the menu will be rendered and testable.

Select Props

| Name | Type | Default | Required | Description | | ---------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | allowCreateWhileLoading | boolean | false | false | Allow creating new options while async options are loading. | | ariaLabel | string | null | false | Accessibility label for assistive technologies. | | ariaLabelledBy | string | null | false | Id of the component being labeled for assistive technologies. | | asyncSearch | boolean | false | false | Enable async search for options. | | autoComplete | string | undefined | false | HTML autocomplete token for browser autofill support (e.g. 'address-level1', 'country', 'off'). When set, the component renders a visually-hidden native <select> with this attribute so browsers can discover and fill the field. The autofilled value is matched against the provided options and fires the onChange callback just like a manual selection. | | autoComplete | string | null | false | HTML autocomplete token for browser autofill support (e.g. 'address-level1', 'country', 'off'). When set, a visually-hidden native select is rendered alongside the component so browsers can discover and autofill the field. The autofilled value is matched against the provided options and fires the onChange callback just like a manual selection. | | cacheOptions | boolean | true | false | Enable caching of options. | | cancelLabel | string | 'Cancel' | false | Label for the Cancel button on the multi-select label. | | categoryNameKey | string | 'categoryName' | false | Name of the key for category name in options. | | categoryValueKey | string | 'categoryValue' | false | Name of the key for category value in options. | | className | string | undefined | false | The css class name to be passed through to the component markup. | | clearable | boolean | false | false | If true select is clearable. | | confirmLabel | string | 'Confirm' | false | Label for the Confirm button on the multi-select label. | | containerProps | object | null | false | Custom properties to be passed to the react-select instance. | | creatable | boolean | false | false | Enable creating new options using the input value. | | defaultOpen | boolean | false | false | The menu will be visible by default. | | defaultOptions | boolean | object | false | false | The defaultOptions prop determines "when" your remote request is initially fired. There are two valid values for this property. Providing an option array to this prop will populate the initial set of options used when opening the select, at which point the remote load only occurs when filtering the options (typing in the control). Providing the prop by itself (or with 'true') tells the control to immediately fire the remote request, described by your onLoadOptions, to get those initial values for the Select. | | dense | boolean | false | false | Styles the select in a more compact format. When used with filled an external label must be used. Dense is not recommended when using as a multi select and `multiDisplayType` is set to pills. | | disabled | boolean | false | false | Prevents the user from interacting with the component. | | filterConfig | object | { 'ignoreCase': true, 'ignoreAccents': true, 'matchFrom': 'any', 'stringify': option => `${option.label} ${option.value}`, 'trim': true } | false | Custom configuration for the select filter. | | filterFunction | function | undefined | false | Custom filter function. | | fixedHeightInput | boolean | false | false | If true the select input will remain the same height even if rendered selections exceed the max height. | | fixedHeightInput | boolean | false | false | If true the select input will remain the same height even if rendered selections exceed the max height. | | formatCreateLabel | function | null | false | Function to format the create option label when `creatable` is true. | | groupNameKey | string | 'groupName' | false | Name of the key for group name in options. | | groupValueKey | string | 'groupValue' | false | Name of the key for group value in options. | | helperText | string | null | false | Helper text to be displayed below Select, by default only visible on focus. | | helperTextId | string | undefined | false | Randomly generated id for the helper text container element. May be overwritten. | | helperTextPersistent | boolean | false | false | Set the helper text to be permanently visible. | | helperTextValidation | boolean | false | false | Set the helper text to use validation styles. Helper text changes with `valid` (e.g., helper text will appear the current theme's danger color when `valid` is set to 'false'). | | hideSelectedOptions | boolean | false | false | Remove the selection option(s) from the list. | | hoisted | boolean | false | false | Whether or not the menu is hoisted to render outside of the parent element. Useful for when the select needs to render in a parent with `overflow: hidden`. Note, `hoisted` will disable `menuPosition`. | | id | string | null | false | Overwrite the default, randomly generated id. Each must be unique. | | inlineLabelWidth | string | undefined | false | An optional width for the label when `labelPosition` is set to `inline`. Can be any valid CSS width value (px, %, em, rem, etc). | | isValidNewOption | function | null | false | Function to determine whether the current input value is a valid new option when `creatable` is true. | | label | string | null | false | The placeholder/floating display label. | | labelPosition | string | 'floating' | false | Controls the position and style of the select label. Possible values: 'floating' (the label appears above the select input and floats when focused or filled), 'inline' (the label is left-aligned and displayed next to the select input, following form layout conventions).Accepted Values: floating, inline | | leadingIcon | string|React.ReactNode | null | false | Accepts the name of any valid material icon (see Icon component documentation for a list of valid icons). | | menuMaxHeight | string | undefined | false | Max height the menu may take up. If using groups, we recommend adding a menu max height. | | menuPosition | string | 'auto' | false | The direction the menu will open. Auto will attempt to open the menu upwards when appropriate, but this can be explicitly set as well. Note, `hoisted` will disable `menuPosition`.Accepted Values: auto, bottom, top | | minimumInputLength | number | 0 | false | Minimum number of characters required to trigger a search. | | multiDisplayTextValue | string | 'items selected' | false | When a multiselect with multiDisplayType='text' and fixedHeightInput prop is passed, the custom text for multilingual support text can be passed. Defaults to '{# of} items selected' | | multiDisplayType | string | 'pills' | false | How value is displayed if select is a multiselect.Accepted Values: pills, text | | multiSelect | boolean | false | false | Enable multi-selection mode. Note, row highlighting is disabled when using multi-select. | | name | string | null | false | Name to be added to hidden html input. | | noOptionsMessage | string|React.ReactNode | 'No options' | false | Message to show if no options are available. | | onCreateOption | function | null | false | Function that executes after a new option is created when `creatable` is true. | | open | boolean | undefined | false | The menu will always be visible. | | optionFilterLabel | string | 'Show only selected options' | false | (??) When using multi-select mode the menu items will show a switch to show all options or only selected. | | options | [object] | [string] | [number] | null | false | Options for select. See README for schema architecture. Options should not be used with children. If both are sent children will be ignored. | | optionsLimit | number | 5 | false | The maximum number of options to display in the dropdown from the search results. | | portalContainer | string|React.ReactNode | undefined | false | The DOM element the menu should render in if `hoisted` is set to true. If a string is sent it should be a valid DOM query selector. If one is not sent, Portal will default to `document.body`. | | rawOptions | boolean | false | false | When true the handleChange will return you the original object/string structure | | readOnly | boolean | false | false | When true, prevents the user from modifying the selected values while keeping the component interactive for scrolling. | | requireConfirmation | boolean | false | false | When in multi-select mode a confirmation will be required before the onChange will be called. | | required | boolean | false | false | Whether or not the input is required. Can be used for validation purposes. | | scrollable | boolean | false | false | If true, wrapping will be disabled and a scrollable area will be created. | | searchDebounceMs | number | 300 | false | Debounce time in milliseconds for onLoadOptions function to be executed. | | searchable | boolean | false | false | Enable autocomplete behavior. | | selectAllLabel | string | 'Select All Options' | false | Label for the Select All checkbox. | | selectOnTab | boolean | false | false | The currently highlighted item will be select when tabbing to the next field. | | showCheckboxOptions | boolean | true | false | When using a multi-select list the items will have checkboxes to indicate selection. If false, options will not have a checkbox, and selected options will be removed from the list. | | showOptionFilter | boolean | true | false | When using a multi-select mode the menu will include a switch to show all options or only selected. | | showSelectAll | boolean | true | false | Shows a checkbox to select all options. | | style | object | null | false | Passthrough style object. | | suppressInvalidOptionWarning | boolean | false | false | Prevent console warning when value is not found in the options list. | | textKey | string | 'text' | false | Name of the key for the text in options. | | themeColor | string | 'primary' | false | Color of the select based on the theme.Accepted Values: primary, secondary | | tooltip | object | null | false | If defined, a Tooltip will appear on the Select input. Useful to show the full value, if selected value is too long for the Select width. The object should be the needed Tooltip properties. Tooltip `text`prop will be set to the current selected value of the Select. See Tooltip docs for available props. | | valid | boolean | null | false | Whether or not the selected value is valid. Can be used for validation purposes. | | value | [object]|object|string|number | undefined | false | The value of the select. | | valueKey | string | 'value' | false | Name of the key for the value in options.