@coreui/react-pro

import React, { HTMLAttributes, ReactNode } from 'react'; import { CFormControlWrapperProps } from '../form/CFormControlWrapper'; import type { Option, OptionsGroup, Search, SelectionActions, SelectionState } from './types'; export interface CMultiSelectProps extends Omit<CFormControlWrapperProps, 'floatingClassName' | 'floatingLabel'>, Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> { /** * Allow users to create options if they are not in the list of options. * * @since 4.11.0 */ allowCreateOptions?: boolean; /** * A string that provides an accessible label for the cleaner button. This label is read by screen readers to describe the action associated with the button. * * @since 5.8.0 */ ariaCleanerLabel?: string; /** * A string that provides an accessible label for the indicator button. This label is read by screen readers to describe the action associated with the button. * * @since 5.19.0 */ ariaIndicatorLabel?: string; /** * Accessible label for the search input (when `search` is enabled). * * @since 5.26.0 */ ariaSearchLabel?: string; /** * Accessible label prefix for a tag's delete button (selection type `tags`). The selected option's label is appended, so screen readers announce e.g. "Remove Angular". * * @since 5.26.0 */ ariaTagDeleteLabel?: string; /** * A string of all className you want applied to the base component. */ className?: string; /** * Enables selection cleaner element. */ cleaner?: boolean; /** * Clear current search on selecting an item. * * @since 4.11.0 */ clearSearchOnSelect?: boolean; /** * Appends the dropdown to a specific element. You can pass an HTML element or function that returns a single element. * * @since 5.8.0 */ container?: DocumentFragment | Element | (() => DocumentFragment | Element | null) | null; /** * Toggle the disabled state for the component. */ disabled?: boolean; /** * Render a custom dropdown header (the area above the options list), replacing the built-in select all button. Receives a `state` object (`{ selected, total, filtered, filteredSelected }`) and an `actions` object (`{ selectAll, deselectAll, selectFiltered, deselectFiltered }`) so you can wire your own controls. Renders independently of `selectAll`. * * @since 5.26.0 */ headerTemplate?: (state: SelectionState, actions: SelectionActions) => ReactNode; /** * Set the id attribute for the native select element. * * **[Deprecated since v5.3.0]** The name attribute for the native select element is generated based on the `id` property: * - `<select name="\{id\}-multi-select" />` */ id?: string; /** * When set, the options list will have a loading style: loading spinner and reduced opacity. * * @since 4.11.0 */ loading?: boolean; /** * It specifies that multiple options can be selected at once. */ multiple?: boolean; /** * The name attribute for the select element. * * @since 5.3.0 */ name?: string; /** * Execute a function when a user changes the selected option. */ onChange?: (selected: Option[]) => void; /** * Execute a function when the filter value changed. * * @since 4.8.0 */ onFilterChange?: (value: string) => void; /** * The callback is fired when the Multi Select component requests to be hidden. */ onHide?: () => void; /** * Execute a function when the user tries to select more options than allowed by `selectionLimit`. * * @since 5.26.0 */ onSelectionLimit?: (selectionLimit: number) => void; /** * The callback is fired when the Multi Select component requests to be shown. */ onShow?: () => void; /** * List of option elements. */ options: (Option | OptionsGroup)[]; /** * Sets maxHeight of options list. */ optionsMaxHeight?: number | string; /** * Sets option style. */ optionsStyle?: 'checkbox' | 'text'; /** * Custom template for options. * * @since 4.12.0 */ optionsTemplate?: (option: Option) => ReactNode; /** * Makes each options group label a toggle that selects or deselects all options in that group. With `optionsGroupsStyle="checkbox"` (and `multiple`) the label shows a tri-state checkbox indicator (`none` / `all` / `indeterminate`) reflecting the group's selection. * * @since 5.26.0 */ optionsGroupsSelectable?: boolean; /** * Sets the options group label style when `optionsGroupsSelectable` is enabled. * * @since 5.26.0 */ optionsGroupsStyle?: 'checkbox' | 'text'; /** * Custom template for options groups. * * @since 4.12.0 */ optionsGroupsTemplate?: (option: OptionsGroup) => ReactNode; /** * Specifies a short hint that is visible in the search input. */ placeholder?: string; /** * Generates dropdown menu using createPortal. * * @since 5.8.0 */ portal?: boolean; /** * When it is present, it indicates that the user must choose a value before submitting the form. */ required?: boolean; /** * Determines whether the selected options should be cleared when the options list is updated. When set to true, any previously selected options will be reset whenever the options list undergoes a change. This ensures that outdated selections are not retained when new options are provided. * * @since 5.3.0 */ resetSelectionOnOptionsChange?: boolean; /** * The `search` prop determines how the search input element is enabled and behaves. It accepts multiple types to provide flexibility in configuring search behavior: * * - `true` : Enables the default search input element with standard behavior. * - `'external'`: Enables an external search mechanism, possibly integrating with external APIs or services. * - `'global'`: When set, the user can perform searches across the entire component, regardless of where their focus is within the component. * - `{ external?: boolean; global?: boolean }`: Allows for granular control over the search behavior by specifying individual properties. It is useful when you also want to use external and global search. */ search?: Search; /** * Sets the label for no results when filtering. */ searchNoResultsLabel?: string | ReactNode; /** * Sets the select all button label shown once everything is selected. The button is a toggle: it shows `selectAllLabel` (and selects all) until everything is selected, then shows `deselectAllLabel` (and deselects all). * * @since 5.26.0 */ deselectAllLabel?: string | ReactNode; /** * Sets the deselect filtered button label (selection type `selectAllMode="filtered"`). * * @since 5.26.0 */ deselectFilteredLabel?: string | ReactNode; /** * Enables select all button. */ selectAll?: boolean; /** * Sets the select all button label. */ selectAllLabel?: string | ReactNode; /** * Determines what the select all button operates on: all options (`'all'`) or only the currently filtered (search-visible) options (`'filtered'`). * * @since 5.26.0 */ selectAllMode?: 'all' | 'filtered'; /** * Sets the select all button style. With `'checkbox'` (and `multiple`), the button shows a tri-state checkbox indicator (`none` / `all` / `indeterminate`) and toggles between selecting and deselecting. * * @since 5.26.0 */ selectAllStyle?: 'checkbox' | 'text'; /** * Sets the select filtered button label (used with `selectAllMode="filtered"`). * * @since 5.26.0 */ selectFilteredLabel?: string | ReactNode; /** * Sets the maximum number of options that can be selected. The select all button stays enabled and selects options up to the limit, then toggles to deselect all once the limit is reached. The `onSelectionLimit` callback fires when a user tries to select more options than allowed. * * @since 5.26.0 */ selectionLimit?: number; /** * Sets the selection style. */ selectionType?: 'counter' | 'tags' | 'text'; /** * Sets the counter selection label. */ selectionTypeCounterText?: string; /** * Size the component small or large. */ size?: 'sm' | 'lg'; /** * Sets the initially selected values for the multi-select component. * * @since 5.13.0 */ value?: string | number | (string | number)[]; /** * Enable virtual scroller for the options list. * * @since 4.8.0 */ virtualScroller?: boolean; /** * Toggle the visibility of multi select dropdown. */ visible?: boolean; /** * Amount of visible items when virtualScroller is set to `true`. * * @since 4.8.0 */ visibleItems?: number; } export declare const CMultiSelect: React.ForwardRefExoticComponent<CMultiSelectProps & React.RefAttributes<HTMLDivElement>>;