This component is part of CoreUI PRO – a powerful UI library with over 250 components and 25+ templates, designed to help you build modern, responsive apps faster. Fully compatible with Angular, Bootstrap, React.js, and Vue.js.

Ger CoreUI PRO

Customize the native <select>s with a powerful React Multi Select component that changes the element’s initial appearance and brings some new functionalities.

Other Frameworks

CoreUI components are available as native Angular, Bootstrap (Vanilla JS), and Vue components. To learn more please visit the following pages.

• Angular Multi Select
• Bootstrap Multi Select
• Vue Multi Select

Basic example#

A clear demonstration of implementing a basic React Multi Select dropdown, highlighting essential options and configurations.

Search#

You can configure the search functionality within the component. Thesearch property determines how the search input element is enabled and behaves. It accepts multiple types to provide flexibility in configuring search behavior. By default is set totrue.

Disabled search#

To disable the default search input element, please setsearch property tofalse like in the example below:

Global search#

To enable the global search functionality within the React Multi Select component, please setsearch property to'global'. When global search is turned on, the user can perform searches across the entire component, regardless of where their focus is within the component. This allows for a more flexible and intuitive search experience, ensuring the search input is recognized from any point within the component.

External search#

When external search is enabled (search="external"), the component delegates search operations to an external API. This setup is ideal for scenarios where third-party services or custom backend implementations power search capabilities.

<CMultiSelectoptions={...}onFilterChange={...}search="external"/>

If you want to enable both external (API-handled) and global search:

<CMultiSelectoptions={...}onFilterChange={...}search={{external:true,global:true}}/>

Please check theExternal Data section to check a working example of how to handle external data.

Modes#

Allow create options#

TheallowCreateOptions property in the<CMultiselect /> component allows users to create new options in addition to selecting pre-existing ones from a list.

When this property is set to true, the user can type in a new option in the search input field of the multiselect component, and if the option does not already exist in the list, it will be created and added to the list of available options. This can be useful when the list of available options is not comprehensive or when the user needs to select an option that is not already available.

Clear search on select#

TheclearSearchOnSelect property is a Boolean attribute that can be used with the MultiSelect component in the CoreUI React library.

WhenclearSearchOnSelect is set totrue, the search input field in the MultiSelect component will be cleared as soon as the user selects an option from the dropdown list. This means that the search query will be reset and the user will be able to start a new search immediately.

By default,clearSearchOnSelect is set tofalse, which means that the search input field will retain the user's search query even after an option has been selected. This can be useful in situations where the user needs to select multiple options from the dropdown list that match the same search query.

To use theclearSearchOnSelect property with the MultiSelect component in the CoreUI React library, you simply need to set it totrue orfalse as appropriate in your code. For example:

In this example, theclearSearchOnSelect property is set totrue, which means that the search input field will be cleared as soon as the user selects an option from the dropdown list.

Selection types#

The React Multi Select component enables users to present selected items in multiple ways. Users can choose to display selected items as a counter, tags, or a list of comma-separated values.

To change the way that selected items are displayed, you can use theselectionType property to set the presentation type.

Tags#

By default, theselectionType property is set to"tags", which displays selected options as tags. Users can remove a selected option by pressing the "X" button.

Counter#

In the example below, selected items from the list are counted and presented in the form of a counter. To use this option, set theselectionType to"counter".

To further customize the counter, theselectionTypeCounterText property allows you to set the text that is displayed after the counter.

Text#

To display the list of selected options as comma-separated text values, set theselectionType property to"text".

Single Selection#

Set themultiple boolean property tofalse and allow select only one element.

Custom options and options group labels#

The CoreUI React Multi Select component provides the flexibility to personalize options and group labels by utilizing custom templates. You can easily customize the options using theoptionsTemplate, and for groups, you can useoptionsGroupsTemplate, as demonstrated in the examples below:

Coordinated selection#

The selection of React select components can be coordinated by dynamically updating city options based on the selected country. Use theresetSelectionOnOptionsChange prop on the city select component to reset the selected city whenever the country changes, ensuring synchronized selections.

Disabled#

Add thedisabled boolean property to give it a grayed out appearance, remove pointer events, and prevent focusing.

Sizing#

You may also choose from small and large multi selects to match our similarly sized text inputs.

Virtual Scroller (1000 records)#

To enhance performance and manage large amounts of data in React Multi Select, you can generate a list of options using<CVirtualScroller />. This component renders only the items currently visible on the screen, and as the user scrolls, new items are dynamically loaded and added to the view. This helps to reduce the data load and processing time, resulting in a more responsive UI.

To enable Virtual Scroller, simply set thevirtualScroller boolean property totrue, as shown in the example below.

External Data#

One of the key features of React Multi Select component is the ability to load data from an external source, such as an API or a server-side script. This can be useful if you have a large amount of data that you don't want to load all at once. To load external data into a React MultiSelect, you can use the Fetch API to the data source.

Here is an example of how you might use React Multi Select with external data:

This example requires the following import:

import{ useDebouncedCallback}from'@coreui/react-pro'

• useDebouncedCallback is a utility hook available in@coreui/react-pro that allows you to debounce a callback function, ensuring it is not called too frequently (e.g., when typing in a search field).
• In this case, it is used to debounce the API call made bygetUsers to reduce the number of requests during rapid input changes.

To handle a large amount of data and improve performance, this example uses the<CVirtualScroller /> component to show the options list.

Accessibility#

The CoreUI React Multi Select component is designed with accessibility in mind and follows WAI-ARIA guidelines to ensure it works well with assistive technologies like screen readers.

Built-in Accessibility Features#

The Multi Select component includes several accessibility features out of the box:

• ARIA Roles: Propercombobox andlistbox roles for screen reader compatibility
• ARIA States: Dynamicaria-expanded,aria-selected, andaria-disabled attributes
• Keyboard Navigation: Full keyboard support with arrow keys, Enter, Space, and Escape
• Focus Management: Proper focus handling when opening/closing the dropdown
• Screen Reader Labels: Descriptive labels for interactive elements

Customizing Accessibility Labels#

You can customize the accessibility labels for better user experience:

<CMultiSelect
options={options}
ariaCleanerLabel="Clear all selected items"
ariaIndicatorLabel="Open options menu"
placeholder="Choose your options..."
/>

ARIA Attributes#

The component automatically handles these ARIA attributes:

• aria-expanded: Indicates whether the dropdown is open or closed
• aria-haspopup="listbox": Tells screen readers that the control opens a listbox
• aria-multiselectable="true": Indicates multiple selections are allowed
• aria-selected: Shows which options are currently selected
• aria-disabled: Identifies disabled options
• aria-owns: Connects the input with the dropdown when using portal mode

Keyboard Navigation#

The Multi Select component supports full keyboard navigation:

Best Practices#

For optimal accessibility, consider these recommendations:

1. Always provide a label: Use thelabel prop or associate with a<label> element
2. Use descriptive placeholder text: Help users understand what to select
3. Provide clear option labels: Ensure option text is descriptive and unique
4. Consider color contrast: Ensure sufficient contrast for visual indicators
5. Test with screen readers: Verify the component works with assistive technologies

<CMultiSelect
label="Select your preferred programming languages"
placeholder="Choose languages..."
options={[
{value:'js',label:'JavaScript'},
{value:'ts',label:'TypeScript'},
{value:'py',label:'Python'}
]}
invalid={hasError}
feedback="Please select at least one language"
/>

API#

Check out the documentation below for a comprehensive guide to all the props you can use with the components mentioned here.

• <CMultiSelect />