@element-public/react-select

v1.0.0

Published

2 months ago

Select component for Element React

Downloads

0High
0Medium
0Low

peon125

slowikowskiarkadiusz

arkadiusz.slowikowski

Select

Description

Select provides a single-option select menu.

See live demos on storybook

Storybook Select Demos

Install bundle from npm-e

npm i @element-public/react-components @element-public/themes

Optional: install the component individually

npm i @element-public/react-select @element-public/themes

Open ~/.npmrc in an editor and add the following line to enable the @element-public scope:


@element-public:registry=https://npm.platforms.engineering

Troubleshooting

See below if you have never installed a package from Bayer's npm-enterprise or run into the following error:


npm ERR! code E401
npm ERR! Unable to authenticate, your authentication token seems to be invalid.
npm ERR! To correct this please trying logging in again with:
npm ERR!     npm login

Setup an access token

See the devtools npm-e guide to learn how to create an access token if this is the first time you are using a npm-e package at Bayer or you do not have a line that starts with the following in your ~/.npmrc file:

//npm.platforms.engineering/:_authToken=

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 | | ---------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ariaLabel | string | null | false | Accessibility label for assistive technologies. | | ariaLabelledBy | string | null | false | Id of the component being labeled for assistive technologies. | | 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. | | defaultOpen | boolean | false | false | The menu will be visible by default. | | 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. | | 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. | | label | string | null | false | The placeholder/floating display label. | | 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 | | 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. | | 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. | | 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. | | 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. | | 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 textprop 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. | | variant | string | 'filled' | false | Applies the selected style to the select input.Accepted Values: filled, outlined |

Select Deprecated Props

| Name | Type | Default | Required | Deprecated | Description | | ------------ | ------- | --------- | -------- | ------------------------------------------ | -------------------------------------------------- | | isClearable | boolean | undefined | false | Renamed to clearable for consistency. | If true select is clearable. | | isMulti | boolean | undefined | false | Renamed to multiSelect for consistency. | If true select is a multi-select. | | valueDisplay | string | undefined | false | Renamed to multiDisplayType for clarity. | How value is displayed if select is a multiselect. |

Select Render Props

| Name | Type | Default | Required | Description | | -------- | --------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- | | children | React.ReactNode | null | false | Expects one or more SelectOption components. Options should not be used with children. If both are sent children will be ignored. |

Select Events

| Name | Default | Required | Params | Description | | ------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | onBlur | null | false | | Fired when the Select looses focus. | | onChange | null | false | 1. Name: value, Type: string, Description: Value that is selected.,2. Name: event, Type: object, Description: The javascript event | Fired when value of the selected option is changed. | | onFocus | null | false | | Fired when the Select gains focus. | | onInputChange | null | false | 1. Name: value, Type: string, Description: Value that is entered into the input.,2. Name: action, Type: object, Description: The action that fired the event. | Fired when the select is searchable and a user changes the search term. |

Select Breaking Changes

| Description | | ---------------------------------------------------------------------------------------------------------------------------------------- | | box (removed): Use variant='filled' instead. | | enhanced (removed): Enhanced is no longer available due to Material Web Components removing native select support. | | filled (removed): Use variant='filled' instead. | | float (removed): This prop is no longer needed. | | fullWidth (removed): Selects are full width by default. Use custom css or a container div to set the width. | | includeEmptyOption (removed): This feature is no longer supported, however you may use clearable to allow select to be easily cleared. | | inputProps (removed): No longer available. | | leadingContent (removed): This feature has been temporarily removed. | | nestedList (removed): No longer needed. | | outlined (removed): Use variant='outlined' instead. | | trailingContent (removed): This feature has been temporarily removed. | | width (removed): Selects are full width by default. Use custom css or a container div to set the width. |

Select Clear Indicator Props

| Name | Type | Default | Required | Description | | ---------- | ------ | --------- | -------- | ---------------------------------- | | innerProps | object | undefined | false | Inner props from the react select. |

Select Confirmation Props

| Name | Type | Default | Required | Description | | ------------ | ------ | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- | | cancelLabel | string | 'Cancel' | false | Label for the Cancel button on the multi select label. | | confirmLabel | string | 'Confirm' | false | Label for the Confirm button on the multi select label. | | themeColor | string | 'primary' | false | Sets the theme color for the option filter switch, confirm/cancel buttons and checkboxesAccepted Values: primary, secondary |

Select Confirmation Events

| Name | Default | Required | Params | Description | | --------- | ------- | -------- | ------ | ----------------------------------- | | onConfirm | null | false | | Fired when confirmation is clicked. |

Select Content Props

| Name | Type | Default | Required | Description | | --------- | ------- | --------- | -------- | ------------------------------------------------------------------------------------------------ | | className | string | undefined | false | The css class name to be passed through to the component markup. | | leading | boolean | undefined | false | Indicates the content will appear before the list, otherwise content will assume it is trailing. |

Select Content Render Props

| Name | Type | Default | Required | Description | | -------- | --------------- | ------- | -------- | ---------------------------------------------------------------------- | | children | React.ReactNode | null | true | Content to be rendered inside the component. Accepts any valid markup. |

Select Control Component Props

| Name | Type | Default | Required | Description | | ----------- | ------- | ------- | -------- | -------------------------------------- | | hasValue | boolean | null | false | Whether or not the select has a value. | | innerProps | object | null | false | Inner props from the react select. | | isFocused | boolean | null | false | Whether or not the select is focused. | | selectProps | object | null | false | Select props sent to react select. |

Select Control Component Render Props

| Name | Type | Default | Required | Description | | -------- | --------------- | ------- | -------- | -------------------------------------------- | | children | React.ReactNode | null | false | Expects the value containers and indicators. |

Select Indicators Container Render Props

| Name | Type | Default | Required | Description | | -------- | --------------- | ------- | -------- | ----------------------- | | children | React.ReactNode | null | false | Expects the indicators. |

Select Label Props

| Name | Type | Default | Required | Description | | ---------------- | ------- | ------------ | -------- | --------------------------------------------------------- | | extendedHeight | boolean | null | false | Whether or not the select control has expanded in height. | | fixedHeightInput | boolean | null | false | Whether or not the select control has a fixed height. | | float | boolean | null | false | Whether or not the label should float. | | isOutlined | boolean | null | false | Whether or not the select is the outlined variant. | | label | string | empty string | false | Label for the select. | | selectId | string | empty string | false | Id for the select. | | selectProps | object | null | false | Select props sent to react select. |

Select Label Render Props

Select Menu Props

| Name | Type | Default | Required | Description | | ----------- | -------- | ------- | -------- | ---------------------------------- | | getValue | function | null | false | Returns the value of the select. | | selectProps | object | null | false | Select props sent to react select. | | setValue | function | null | false | Set the value of the select. |

Select Menu Render Props

Select Menu List Props

| Name | Type | Default | Required | Description | | ----------- | ------ | ------- | -------- | ---------------------------------- | | selectProps | object | null | false | Select props sent to react select. |

Select Menu List Render Props

Select Multi Value Render Props

Select Multi Value Label Render Props

Select Option Props

| Name | Type | Default | Required | Description | | ------------- | ------------------------------- | --------- | -------- | ----------------------------------------------------- | | data | object | undefined | false | Data for the select option. | | disabled | boolean | undefined | false | Prevent the user from interacting with the component. | | getValue | function | undefined | false | Returns the value of the select. | | innerProps | object | undefined | false | Inner props from the react select. | | isChildOption | boolean | false | false | The option is nested. | | isFocused | boolean | undefined | false | Whether or not the option is focused. | | isSelected | boolean | undefined | false | Whether or not the select is selected. | | label | string|number|React.ReactNode | undefined | false | The display value of the SelectOption. | | selectProps | object | undefined | false | Select props sent to react select. | | setValue | function | undefined | false | Sets the value of the select. | | value | any | undefined | false | The value of the SelectOption. |

Select Option Deprecated Props

| Name | Type | Default | Required | Deprecated | Description | | -------- | ------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | | selected | boolean | undefined | false | The parent Select component will manage the selected state of child SelectOptions. If this is set, it will only change the appearance of the option to show as highlighted. | Whether or not the select is selected. |

Select Option Render Props

| Name | Type | Default | Required | Description | | -------- | --------------- | --------- | -------- | ----------------------------------------------------------------------------------------------------------------- | | children | React.ReactNode | undefined | false | The display value of the SelectOption. If using more than a simple string or number, custom css may be necessary. |

Select Option Filter Props

| Name | Type | Default | Required | Description | | ------------------------ | -------- | ------------ | -------- | -------------------------------------------------------------------- | | optionFilterLabel | string | empty string | false | Label for the option filter switch. | | optionFilterThemeColor | string | empty string | false | Theme color for the switch.Accepted Values: primary, secondary | | setShowOnlySelectedItems | function | null | false | Sets the value of the showOnlySelectedItems prop. | | showOnlySelectedItems | boolean | null | false | If true only selected items are shown in the menu. |

Select Portal Props

| Name | Type | Default | Required | Description | | ------------ | -------- | ------------ | -------- | ------------------------------------ | | getStyles | function | null | false | Returns the styles of the component. | | menuPosition | string | empty string | false | Position of the select menu. |