@carbon/react

/** * Copyright IBM Corp. 2016, 2025 * * This source code is licensed under the Apache-2.0 license found in the * LICENSE file in the root directory of this source tree. */ import { type UseComboboxProps, type UseMultipleSelectionProps } from 'downshift'; import React, { type FunctionComponent, type ReactElement, type ReactNode } from 'react'; import { type MultiSelectSortingProps } from './MultiSelectPropTypes'; import { type ListBoxSize, type ListBoxType } from '../ListBox'; import { TranslateWithId } from '../../types/common'; /** * Message ids that will be passed to translateWithId(). * Combination of message ids from ListBox/next/ListBoxSelection.js and * ListBox/next/ListBoxTrigger.js, but we can't access those values directly * because those components aren't Typescript. (If you try, TranslationKey * ends up just being defined as "string".) */ type TranslationKey = 'close.menu' | 'open.menu' | 'clear.all' | 'clear.selection'; export interface FilterableMultiSelectProps<ItemType> extends MultiSelectSortingProps<ItemType>, React.RefAttributes<HTMLDivElement>, TranslateWithId<TranslationKey> { /** * Specify a label to be read by screen readers on the container node * @deprecated */ 'aria-label'?: string; /** @deprecated */ ariaLabel?: string; /** * **Experimental**: Will attempt to automatically align the floating * element to avoid collisions with the viewport and being clipped by * ancestor elements. Requires React v17+ * @see https://github.com/carbon-design-system/carbon/issues/18714 */ autoAlign?: boolean; className?: string; /** * Specify the text that should be read for screen readers that describes total items selected */ clearSelectionDescription?: string; /** * Specify the text that should be read for screen readers to clear selection. */ clearSelectionText?: string; /** * **Experimental**: Provide a `decorator` component to be rendered inside the `FilterableMultiSelect` component */ decorator?: ReactNode; /** * Specify the direction of the multiselect dropdown. */ direction?: 'top' | 'bottom'; /** * Disable the control */ disabled?: boolean; /** * Additional props passed to Downshift. * * **Use with caution:** anything you define here overrides the components' * internal handling of that prop. Downshift APIs and internals are subject to * change, and in some cases they can not be shimmed by Carbon to shield you * from potentially breaking changes. */ downshiftProps?: UseMultipleSelectionProps<ItemType>; /** * Provide a method that filters the dropdown options based on the current input. Overriding this * prop means that you have to handle the filtering logic when the user types in the text input. * Otherwise, a default built-in filtering function will be used. */ filterItems?(items: readonly ItemType[], extra: { inputValue: string | null; itemToString: NonNullable<UseComboboxProps<ItemType>['itemToString']>; }): ItemType[]; /** * Specify whether the title text should be hidden or not */ hideLabel?: boolean; /** * Provide helper text that is used alongside * the control label for additional help */ helperText?: ReactNode; /** * Specify a custom `id` */ id: string; /** * Allow users to pass in arbitrary items from their collection that are * pre-selected */ initialSelectedItems?: ItemType[]; /** * Is the current selection invalid? */ invalid?: boolean; /** * If invalid, what is the error? */ invalidText?: ReactNode; /** * Function to render items as custom components instead of strings. * Defaults to null and is overridden by a getter */ itemToElement?: FunctionComponent<ItemType>; /** * Helper function passed to downshift that allows the library to render * a given item to a string label. * * By default, it extracts the `label` field from a given item * to serve as the item label in the list. */ itemToString?(item: ItemType | null): string; /** * We try to stay as generic as possible here to allow individuals to pass * in a collection of whatever kind of data structure they prefer */ items: ItemType[]; /** * @deprecated `true` to use the light version. */ light?: boolean; /** * Specify the locale of the control. * Used for the default `compareItems`, * which is used for sorting the list of items in the control. */ locale?: string; /** * `onChange` is a utility for this controlled component to communicate to a * consuming component what kind of internal state changes are occurring. */ onChange?(changes: { selectedItems: ItemType[]; }): void; /** * A utility for this controlled component * to communicate to the currently typed input. */ onInputValueChange?: UseComboboxProps<ItemType>['onInputValueChange']; /** * `onMenuChange` is a utility for this controlled component to communicate to a * consuming component that the menu was opened(`true`)/closed(`false`). */ onMenuChange?(open: boolean): void; /** * Initialize the component with an open(`true`)/closed(`false`) menu. */ open?: boolean; /** * Generic `placeholder` that will be used as the textual representation of * what this field is for */ placeholder?: string; /** * Whether or not the filterable multiselect is readonly */ readOnly?: boolean; /** * Specify feedback (mode) of the selection. * `top`: selected item jumps to top * `fixed`: selected item stays at its position * `top-after-reopen`: selected item jump to top after reopen dropdown */ selectionFeedback?: 'top' | 'fixed' | 'top-after-reopen'; /** * For full control of the selected items */ selectedItems?: ItemType[]; /** * Specify the size of the ListBox. * Currently, supports either `sm`, `md` or `lg` as an option. */ size?: ListBoxSize; /** * @deprecated please use decorator instead. * **Experimental**: Provide a `Slug` component to be rendered inside the `Checkbox` component */ slug?: ReactNode; /** * Provide text to be used in a `<label>` element that is tied to the * combobox via ARIA attributes. */ titleText?: ReactNode; type?: ListBoxType; /** * Specify title to show title on hover */ useTitleInItem?: boolean; /** * Specify whether the control is currently in warning state */ warn?: boolean; /** * Provide the text that is displayed when the control is in warning state */ warnText?: ReactNode; /** * Specify native input attributes to place on the `<input>`, like maxLength. * These are passed to downshift's getInputProps() and will override the * internal input props. * https://github.com/downshift-js/downshift?tab=readme-ov-file#getinputprops */ inputProps?: React.InputHTMLAttributes<HTMLInputElement>; } export declare const FilterableMultiSelect: { <ItemType>(props: FilterableMultiSelectProps<ItemType>): ReactElement<any>; propTypes?: any; contextTypes?: any; defaultProps?: any; displayName?: any; }; export {};