@carbon/react
Version:
React components for the Carbon Design System
185 lines (184 loc) • 6.5 kB
TypeScript
/**
* 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 { UseSelectProps } from 'downshift';
import React, { type ReactNode } from 'react';
import { type ListBoxSize, type ListBoxType } from '../ListBox';
import { MultiSelectSortingProps } from './MultiSelectPropTypes';
import { ListBoxProps } from '../ListBox/ListBox';
import type { TranslateWithId } from '../../types/common';
interface OnChangeData<ItemType> {
selectedItems: ItemType[] | null;
}
export interface MultiSelectProps<ItemType> extends MultiSelectSortingProps<ItemType>, TranslateWithId<'close.menu' | 'open.menu' | 'clear.all' | 'clear.selection'> {
/**
* **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 that all items are deleted
*/
clearAnnouncement?: 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 `MultiSelect` component
*/
decorator?: ReactNode;
/**
* Specify the direction of the multiselect dropdown. Can be either top or bottom.
*/
direction?: 'bottom' | 'top';
/**
* Disable the control
*/
disabled?: ListBoxProps['disabled'];
/**
* 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?: Partial<UseSelectProps<ItemType>>;
/**
* Provide helper text that is used alongside the control label for
* additional help
*/
helperText?: ReactNode;
/**
* Specify whether the title text should be hidden or not
*/
hideLabel?: boolean;
/**
* 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?: React.JSXElementConstructor<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): 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[];
/**
* Generic `label` that will be used as the textual representation of what
* this field is for
*/
label: NonNullable<ReactNode>;
/**
* `true` to use the light version.
*
* @deprecated The `light` prop for `MultiSelect` has
* been deprecated in favor of the new `Layer` component. It will be removed in the next major release.
*/
light?: boolean;
/**
* Specify the locale of the control. Used for the default `compareItems`
* 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?(data: OnChangeData<ItemType>): void;
/**
* `onMenuChange` is a utility for this controlled component to communicate to a
* consuming component that the menu was open(`true`)/closed(`false`).
*/
onMenuChange?(open: boolean): void;
/**
* Initialize the component with an open(`true`)/closed(`false`) menu.
*/
open?: boolean;
/**
* Whether or not the Dropdown is readonly
*/
readOnly?: boolean;
/**
* For full control of the selected items
*/
selectedItems?: ItemType[];
/**
* Specify feedback (mode) of the selection.
* `top`: selected item jumps to top
* `fixed`: selected item stays at it's position
* `top-after-reopen`: selected item jump to top after reopen dropdown
*/
selectionFeedback?: 'fixed' | 'top' | 'top-after-reopen';
/**
* 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 `MultiSelect` component
*/
slug?: ReactNode;
/**
* Provide text to be used in a `<label>` element that is tied to the
* multiselect via ARIA attributes.
*/
titleText?: ReactNode;
/**
* Specify 'inline' to create an inline multi-select.
*/
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;
}
export declare const MultiSelect: MultiSelectComponent;
type MultiSelectComponentProps<ItemType> = React.PropsWithChildren<MultiSelectProps<ItemType>> & React.RefAttributes<HTMLButtonElement>;
interface MultiSelectComponent {
propTypes: Record<string, any>;
displayName: string;
<ItemType>(props: MultiSelectComponentProps<ItemType>): React.ReactElement<any> | null;
}
export {};