@blueprintjs/select

  • Version 5.1.2
  • Published
  • 813 kB
  • 4 dependencies
  • Apache-2.0 license

Install

npm i @blueprintjs/select
yarn add @blueprintjs/select
pnpm add @blueprintjs/select

Overview

Components related to selecting items from a list

Index

Functions

Classes

Interfaces

Type Aliases

Namespaces

Functions

function executeItemsEqual

executeItemsEqual: <T>(
itemsEqualProp: ItemsEqualProp<T> | undefined,
itemA: T | null | undefined,
itemB: T | null | undefined
) => boolean;
  • Utility function for executing the ListItemsProps#itemsEqual prop to test for equality between two items.

    true if the two items are equivalent according to itemsEqualProp.

function getActiveItem

getActiveItem: <T>(activeItem: T | CreateNewItem | null | undefined) => T | null;
  • Returns the type of the the current active item. This will be a no-op unless the activeItem is undefined or a "Create Item" option, in which case null will be returned instead.

function getCreateNewItem

getCreateNewItem: () => CreateNewItem;
  • Returns an instance of a "Create Item" object.

function isCreateNewItem

isCreateNewItem: <T>(
item: T | CreateNewItem | null | undefined
) => item is CreateNewItem;
  • Type guard returning true if the provided item (e.g. the current activeItem) is a "Create Item" option.

function renderFilteredItems

renderFilteredItems: (
props: ItemListRendererProps<any>,
noResults?: React.ReactNode,
initialContent?: React.ReactNode | null
) => React.ReactNode;
  • ItemListRenderer helper method for rendering each item in filteredItems, with optional support for noResults (when filtered items is empty) and initialContent (when query is empty).

Classes

class MultiSelect

class MultiSelect<T> extends AbstractPureComponent<
MultiSelectProps<T>,
MultiSelectState
> {}
  • Multi select component.

    See Also

    • https://blueprintjs.com/docs/#select/multi-select

property defaultProps

static defaultProps: { disabled: boolean; fill: boolean; placeholder: string };

    property displayName

    static displayName: string;

      property input

      input: HTMLInputElement;

        property queryList

        queryList: QueryList<T>;

          property state

          state: MultiSelectState;

            method componentDidUpdate

            componentDidUpdate: (prevProps: MultiSelectProps<T>) => void;

              method ofType

              static ofType: <U>() => new (props: MultiSelectProps<U>) => MultiSelect<U>;
              • Deprecated

                no longer necessary now that the TypeScript parser supports type arguments on JSX element tags

              method render

              render: () => React.JSX.Element;

                class MultiSelect2

                class MultiSelect<T> extends AbstractPureComponent<
                MultiSelectProps<T>,
                MultiSelectState
                > {}
                • Multi select component.

                  See Also

                  • https://blueprintjs.com/docs/#select/multi-select

                property defaultProps

                static defaultProps: { disabled: boolean; fill: boolean; placeholder: string };

                  property displayName

                  static displayName: string;

                    property input

                    input: HTMLInputElement;

                      property queryList

                      queryList: QueryList<T>;

                        property state

                        state: MultiSelectState;

                          method componentDidUpdate

                          componentDidUpdate: (prevProps: MultiSelectProps<T>) => void;

                            method ofType

                            static ofType: <U>() => new (props: MultiSelectProps<U>) => MultiSelect<U>;
                            • Deprecated

                              no longer necessary now that the TypeScript parser supports type arguments on JSX element tags

                            method render

                            render: () => React.JSX.Element;

                              class Omnibar

                              class Omnibar<T> extends React.PureComponent<OmnibarProps<T>> {}
                              • Omnibar component.

                                See Also

                                • https://blueprintjs.com/docs/#select/omnibar

                              property displayName

                              static displayName: string;

                                method ofType

                                static ofType: <U>() => new (props: OmnibarProps<U>) => Omnibar<U>;

                                  method render

                                  render: () => React.JSX.Element;

                                    class QueryList

                                    class QueryList<T> extends AbstractComponent<QueryListProps<T>, QueryListState<T>> {}
                                    • Query list component.

                                      See Also

                                      • https://blueprintjs.com/docs/#select/query-list

                                    constructor

                                    constructor(props: QueryListProps<T>);

                                      property defaultProps

                                      static defaultProps: { disabled: boolean; resetOnQuery: boolean };

                                        property displayName

                                        static displayName: string;

                                          method componentDidUpdate

                                          componentDidUpdate: (prevProps: QueryListProps<T>) => void;

                                            method ofType

                                            static ofType: <U>() => new (props: QueryListProps<U>) => QueryList<U>;
                                            • Deprecated

                                              no longer necessary now that the TypeScript parser supports type arguments on JSX element tags

                                            method render

                                            render: () => React.JSX.Element;

                                              method scrollActiveItemIntoView

                                              scrollActiveItemIntoView: () => void;

                                                method setActiveItem

                                                setActiveItem: (activeItem: T | CreateNewItem | null) => void;

                                                  method setQuery

                                                  setQuery: (
                                                  query: string,
                                                  resetActiveItem?: boolean | undefined,
                                                  props?: Readonly<QueryListProps<T>> &
                                                  Readonly<{ children?: React.ReactNode }>
                                                  ) => void;

                                                    class Select

                                                    class Select<T> extends AbstractPureComponent<SelectProps<T>, SelectState> {}
                                                    • Select component.

                                                      See Also

                                                      • https://blueprintjs.com/docs/#select/select

                                                    property displayName

                                                    static displayName: string;

                                                      property inputElement

                                                      inputElement: HTMLInputElement;

                                                        property state

                                                        state: SelectState;

                                                          method componentDidUpdate

                                                          componentDidUpdate: (prevProps: SelectProps<T>, prevState: SelectState) => void;

                                                            method ofType

                                                            static ofType: <U>() => new (props: SelectProps<U>) => Select<U>;
                                                            • Deprecated

                                                              no longer necessary now that the TypeScript parser supports type arguments on JSX element tags

                                                            method render

                                                            render: () => React.JSX.Element;

                                                              class Select2

                                                              class Select<T> extends AbstractPureComponent<SelectProps<T>, SelectState> {}
                                                              • Select component.

                                                                See Also

                                                                • https://blueprintjs.com/docs/#select/select

                                                              property displayName

                                                              static displayName: string;

                                                                property inputElement

                                                                inputElement: HTMLInputElement;

                                                                  property state

                                                                  state: SelectState;

                                                                    method componentDidUpdate

                                                                    componentDidUpdate: (prevProps: SelectProps<T>, prevState: SelectState) => void;

                                                                      method ofType

                                                                      static ofType: <U>() => new (props: SelectProps<U>) => Select<U>;
                                                                      • Deprecated

                                                                        no longer necessary now that the TypeScript parser supports type arguments on JSX element tags

                                                                      method render

                                                                      render: () => React.JSX.Element;

                                                                        class Suggest

                                                                        class Suggest<T> extends AbstractPureComponent<SuggestProps<T>, SuggestState<T>> {}
                                                                        • Suggest component.

                                                                          See Also

                                                                          • https://blueprintjs.com/docs/#select/suggest

                                                                        property defaultProps

                                                                        static defaultProps: Partial<SuggestProps<any>>;

                                                                          property displayName

                                                                          static displayName: string;

                                                                            property inputElement

                                                                            inputElement: HTMLInputElement;

                                                                              property state

                                                                              state: SuggestState<T>;

                                                                                method componentDidUpdate

                                                                                componentDidUpdate: (
                                                                                prevProps: SuggestProps<T>,
                                                                                prevState: SuggestState<T>
                                                                                ) => void;

                                                                                  method ofType

                                                                                  static ofType: <U>() => new (props: SuggestProps<U>) => Suggest<U>;
                                                                                  • Deprecated

                                                                                    no longer necessary now that the TypeScript parser supports type arguments on JSX element tags

                                                                                  method render

                                                                                  render: () => React.JSX.Element;

                                                                                    class Suggest2

                                                                                    class Suggest<T> extends AbstractPureComponent<SuggestProps<T>, SuggestState<T>> {}
                                                                                    • Suggest component.

                                                                                      See Also

                                                                                      • https://blueprintjs.com/docs/#select/suggest

                                                                                    property defaultProps

                                                                                    static defaultProps: Partial<SuggestProps<any>>;

                                                                                      property displayName

                                                                                      static displayName: string;

                                                                                        property inputElement

                                                                                        inputElement: HTMLInputElement;

                                                                                          property state

                                                                                          state: SuggestState<T>;

                                                                                            method componentDidUpdate

                                                                                            componentDidUpdate: (
                                                                                            prevProps: SuggestProps<T>,
                                                                                            prevState: SuggestState<T>
                                                                                            ) => void;

                                                                                              method ofType

                                                                                              static ofType: <U>() => new (props: SuggestProps<U>) => Suggest<U>;
                                                                                              • Deprecated

                                                                                                no longer necessary now that the TypeScript parser supports type arguments on JSX element tags

                                                                                              method render

                                                                                              render: () => React.JSX.Element;

                                                                                                Interfaces

                                                                                                interface CreateNewItem

                                                                                                interface CreateNewItem {}
                                                                                                • The reserved type of the "Create Item" option in item lists. This is intended not to conflict with any custom item type T that might be used in item list.

                                                                                                interface ItemListRendererProps

                                                                                                interface ItemListRendererProps<T> {}
                                                                                                • An object describing how to render the list of items. An itemListRenderer receives this object as its sole argument.

                                                                                                property activeItem

                                                                                                activeItem: T | CreateNewItem | null;
                                                                                                • The currently focused item (for keyboard interactions), or null to indicate that no item is active.

                                                                                                property filteredItems

                                                                                                filteredItems: T[];
                                                                                                • Array of items filtered by itemListPredicate or itemPredicate. See items for the full list of items.

                                                                                                  Use renderFilteredItems() utility function from this library to map each item in this array through renderItem, with support for optional noResults and initialContent states.

                                                                                                property items

                                                                                                items: T[];
                                                                                                • Array of all items in the list. See filteredItems for a filtered array based on query and predicate props.

                                                                                                property itemsParentRef

                                                                                                itemsParentRef: React.Ref<HTMLUListElement>;
                                                                                                • A ref handler that should be attached to the parent HTML element of the menu items. This is required for the active item to scroll into view automatically.

                                                                                                property menuProps

                                                                                                menuProps?: React.HTMLAttributes<HTMLUListElement>;
                                                                                                • Props to apply to the Menu created within the itemListRenderer

                                                                                                property query

                                                                                                query: string;
                                                                                                • The current query string.

                                                                                                property renderCreateItem

                                                                                                renderCreateItem: () => React.JSX.Element | null | undefined;
                                                                                                • Call this function to render the "create new item" view component.

                                                                                                  Returns

                                                                                                  null when creating a new item is not available, and undefined if the createNewItemRenderer returns undefined

                                                                                                property renderItem

                                                                                                renderItem: (item: T, index: number) => React.JSX.Element | null;
                                                                                                • Call this function to render an item. This retrieves the modifiers for the item and delegates actual rendering to the owner component's itemRenderer prop.

                                                                                                interface ItemModifiers

                                                                                                interface ItemModifiers {}

                                                                                                  property active

                                                                                                  active: boolean;
                                                                                                  • Whether this is the "active" (focused) item, meaning keyboard interactions will act upon it.

                                                                                                  property disabled

                                                                                                  disabled: boolean;
                                                                                                  • Whether this item is disabled and should ignore interactions.

                                                                                                  property matchesPredicate

                                                                                                  matchesPredicate: boolean;
                                                                                                  • Whether this item matches the predicate. A typical renderer could hide false values.

                                                                                                  interface ItemRendererProps

                                                                                                  interface ItemRendererProps<T extends HTMLElement = HTMLLIElement> {}
                                                                                                  • An object describing how to render a particular item. An itemRenderer receives the item as its first argument, and this object as its second argument.

                                                                                                    Make sure to forward the provided ref to the rendered element (usually via <MenuItem ref={ref} />) to ensure that scrolling to active items works correctly.

                                                                                                    T type of the DOM element rendered for this item to which we can attach a ref (defaults to MenuItem's HTMLLIElement)

                                                                                                  property handleClick

                                                                                                  handleClick: React.MouseEventHandler<HTMLElement>;
                                                                                                  • Click event handler to select this item.

                                                                                                  property handleFocus

                                                                                                  handleFocus?: () => void;
                                                                                                  • Focus event handler to set this as the "active" item.

                                                                                                    N.B. this is optional to preserve backwards-compatibility with @blueprintjs/select version < 4.2.0

                                                                                                  property index

                                                                                                  index: number;
                                                                                                  • Index of the item in the QueryList items array.

                                                                                                  property modifiers

                                                                                                  modifiers: ItemModifiers;
                                                                                                  • Modifiers that describe how to render this item, such as active or disabled.

                                                                                                  property query

                                                                                                  query: string;
                                                                                                  • The current query string used to filter the items.

                                                                                                  property ref

                                                                                                  ref?: React.Ref<T>;
                                                                                                  • A ref attached the native HTML element rendered by this item.

                                                                                                    N.B. this is optional to preserve backwards-compatibilty with @blueprintjs/select version < 4.9.0

                                                                                                  interface ListItemsProps

                                                                                                  interface ListItemsProps<T> extends Props {}
                                                                                                  • Reusable generic props for a component that operates on a filterable, selectable list of items.

                                                                                                  property activeItem

                                                                                                  activeItem?: T | CreateNewItem | null;
                                                                                                  • The currently focused item for keyboard interactions, or null to indicate that no item is active. If omitted or undefined, this prop will be uncontrolled (managed by the component's state). Use onActiveItemChange to listen for updates.

                                                                                                  property createNewItemFromQuery

                                                                                                  createNewItemFromQuery?: (query: string) => T | T[];
                                                                                                  • If provided, allows new items to be created using the current query string. This is invoked when user interaction causes one or many items to be created, either by pressing the Enter key or by clicking on the "Create Item" option. It transforms a query string into one or many items type.

                                                                                                  property createNewItemPosition

                                                                                                  createNewItemPosition?: 'first' | 'last';
                                                                                                  • Determines the position of the createNewItem within the list: first or last. Only relevant when createNewItemRenderer is defined.

                                                                                                    'last'

                                                                                                  property createNewItemRenderer

                                                                                                  createNewItemRenderer?: (
                                                                                                  query: string,
                                                                                                  active: boolean,
                                                                                                  handleClick: React.MouseEventHandler<HTMLElement>
                                                                                                  ) => React.JSX.Element | undefined;
                                                                                                  • Custom renderer to transform the current query string into a selectable "Create Item" option. If this function is provided, a "Create Item" option will be rendered at the end of the list of items. If this function is not provided, a "Create Item" option will not be displayed.

                                                                                                  property initialContent

                                                                                                  initialContent?: React.ReactNode | null;
                                                                                                  • React content to render when query is empty. If omitted, all items will be rendered (or result of itemListPredicate with empty query). If explicit null, nothing will be rendered when query is empty.

                                                                                                    This prop is ignored if a custom itemListRenderer is supplied.

                                                                                                  property itemDisabled

                                                                                                  itemDisabled?: keyof T | ((item: T, index: number) => boolean);
                                                                                                  • Determine if the given item is disabled. Provide a callback function, or simply provide the name of a boolean property on the item that exposes its disabled state.

                                                                                                  property itemListPredicate

                                                                                                  itemListPredicate?: ItemListPredicate<T>;
                                                                                                  • Customize querying of entire items array. Return new list of items. This method can reorder, add, or remove items at will. (Supports filter algorithms that operate on the entire set, rather than individual items.)

                                                                                                    If itemPredicate is also defined, this prop takes priority and the other will be ignored.

                                                                                                  property itemListRenderer

                                                                                                  itemListRenderer?: ItemListRenderer<T>;
                                                                                                  • Custom renderer for the contents of the dropdown.

                                                                                                    The default implementation invokes itemRenderer for each item that passes the predicate and wraps them all in a Menu element. If the query is empty then initialContent is returned, and if there are no items that match the predicate then noResults is returned.

                                                                                                  property itemPredicate

                                                                                                  itemPredicate?: ItemPredicate<T>;
                                                                                                  • Customize querying of individual items.

                                                                                                    __Filtering a list of items.__ This function is invoked to filter the list of items as a query is typed. Return true to keep the item, or false to hide. This method is invoked once for each item, so it should be performant. For more complex queries, use itemListPredicate to operate once on the entire array. For the purposes of filtering the list, this prop is ignored if itemListPredicate is also defined.

                                                                                                    __Matching a pasted value to an item.__ This function is also invoked to match a pasted value to an existing item if possible. In this case, the function will receive exactMatch=true, and the function should return true only if the item _exactly_ matches the query. For the purposes of matching pasted values, this prop will be invoked even if itemListPredicate is defined.

                                                                                                  property itemRenderer

                                                                                                  itemRenderer: ItemRenderer<T>;
                                                                                                  • Custom renderer for an item in the dropdown list. Receives a boolean indicating whether this item is active (selected by keyboard arrows) and an onClick event handler that should be attached to the returned element.

                                                                                                  property items

                                                                                                  items: T[];
                                                                                                  • Array of items in the list.

                                                                                                  property itemsEqual

                                                                                                  itemsEqual?: ItemsEqualProp<T>;
                                                                                                  • Specifies how to test if two items are equal. By default, simple strict equality (===) is used to compare two items.

                                                                                                    If your items have a unique identifier field, simply provide the name of a property on the item that can be compared with strict equality to determine equivalence: itemsEqual="id" will check a.id === b.id.

                                                                                                    If more complex comparison logic is required, provide an equality comparator function that returns true if the two items are equal. The arguments to this function will never be null or undefined, as those values are handled before calling the function.

                                                                                                  property noResults

                                                                                                  noResults?: React.ReactNode;
                                                                                                  • React content to render when filtering items returns zero results. If omitted, nothing will be rendered in this case.

                                                                                                    This prop is ignored if a custom itemListRenderer is supplied.

                                                                                                    NOTE: if passing a MenuItem, ensure it has roleStructure="listoption" prop.

                                                                                                  property onActiveItemChange

                                                                                                  onActiveItemChange?: (activeItem: T | null, isCreateNewItem: boolean) => void;
                                                                                                  • Invoked when user interaction should change the active item: arrow keys move it up/down in the list, selecting an item makes it active, and changing the query may reset it to the first item in the list if it no longer matches the filter.

                                                                                                    If the "Create Item" option is displayed and currently active, then isCreateNewItem will be true and activeItem will be null. In this case, you should provide a valid CreateNewItem object to the activeItem _prop_ in order for the "Create Item" option to appear as active.

                                                                                                    __Note:__ You can instantiate a CreateNewItem object using the getCreateNewItem() utility exported from this package.

                                                                                                  property onItemSelect

                                                                                                  onItemSelect: (item: T, event?: React.SyntheticEvent<HTMLElement>) => void;
                                                                                                  • Callback invoked when an item from the list is selected, typically by clicking or pressing enter key.

                                                                                                  property onItemsPaste

                                                                                                  onItemsPaste?: (items: T[]) => void;
                                                                                                  • Callback invoked when multiple items are selected at once via pasting.

                                                                                                  property onQueryChange

                                                                                                  onQueryChange?: (
                                                                                                  query: string,
                                                                                                  event?: React.ChangeEvent<HTMLInputElement>
                                                                                                  ) => void;
                                                                                                  • Callback invoked when the query string changes.

                                                                                                  property query

                                                                                                  query?: string;
                                                                                                  • Query string passed to itemListPredicate or itemPredicate to filter items. This value is controlled: its state must be managed externally by attaching an onChange handler to the relevant element in your renderer implementation.

                                                                                                  property resetOnQuery

                                                                                                  resetOnQuery?: boolean;
                                                                                                  • Whether the active item should be reset to the first matching item _every time the query changes_ (via prop or by user input).

                                                                                                    true

                                                                                                  property resetOnSelect

                                                                                                  resetOnSelect?: boolean;
                                                                                                  • Whether the active item should be reset to the first matching item _when an item is selected_. The query will also be reset to the empty string.

                                                                                                    false

                                                                                                  property scrollToActiveItem

                                                                                                  scrollToActiveItem?: boolean;
                                                                                                  • When activeItem is controlled, whether the active item should _always_ be scrolled into view when the prop changes. If false, only changes that result from built-in interactions (clicking, querying, or using arrow keys) will scroll the active item into view. Ignored if the activeItem prop is omitted (uncontrolled behavior).

                                                                                                    true

                                                                                                  interface MultiSelect2Props

                                                                                                  interface MultiSelectProps<T> extends ListItemsProps<T>, SelectPopoverProps {}

                                                                                                    property disabled

                                                                                                    disabled?: boolean;
                                                                                                    • Whether the component is non-interactive. If true, the list's item renderer will not be called.

                                                                                                      false

                                                                                                    property fill

                                                                                                    fill?: boolean;
                                                                                                    • Whether the component should take up the full width of its container.

                                                                                                    property menuProps

                                                                                                    menuProps?: React.HTMLAttributes<HTMLUListElement>;
                                                                                                    • Props to spread to the Menu listbox containing the selectable options.

                                                                                                    property onClear

                                                                                                    onClear?: () => void;
                                                                                                    • If provided, this component will render a "clear" button inside its TagInput. Clicking that button will invoke this callback to clear all items from the current selection.

                                                                                                    property onRemove

                                                                                                    onRemove?: (value: T, index: number) => void;
                                                                                                    • Callback invoked when an item is removed from the selection by removing its tag in the TagInput. This is generally more useful than tagInputProps.onRemove because it receives the removed value instead of the value's rendered ReactNode tag.

                                                                                                      It is not recommended to supply _both_ this prop and tagInputProps.onRemove.

                                                                                                    property openOnKeyDown

                                                                                                    openOnKeyDown?: boolean;
                                                                                                    • If true, the component waits until a keydown event in the TagInput before opening its popover.

                                                                                                      If false, the popover opens immediately after a mouse click focuses the component's TagInput.

                                                                                                      N.B. the behavior of this prop differs slightly from the same one in the Suggest component; see https://github.com/palantir/blueprint/issues/4152.

                                                                                                      false

                                                                                                    property placeholder

                                                                                                    placeholder?: string;
                                                                                                    • Input placeholder text. Shorthand for tagInputProps.placeholder.

                                                                                                      "Search..."

                                                                                                    property selectedItems

                                                                                                    selectedItems: T[];
                                                                                                    • Controlled selected values.

                                                                                                    property tagInputProps

                                                                                                    tagInputProps?: Partial<Omit<TagInputProps, 'inputValue' | 'onInputChange'>>;
                                                                                                    • Props to pass to the [TagInput component](##core/components/tag-input).

                                                                                                      Some properties are unavailable: - tagInputProps.inputValue: use query instead - tagInputProps.onInputChange: use onQueryChange instead

                                                                                                      Some properties are available, but discouraged. If you find yourself using these due to a bug in MultiSelect or some edge case which is not handled by onItemSelect, onItemsPaste, onRemove, and onClear, please file a bug in the Blueprint repo: - tagInputProps.onChange

                                                                                                      Notes for tagInputProps.rightElement: - you are responsible for disabling any elements you may render here when the overall MultiSelect is disabled - if the onClear prop is defined, this element will override/replace the default rightElement, which is a "clear" button that removes all items from the current selection.

                                                                                                    property tagRenderer

                                                                                                    tagRenderer: (item: T) => React.ReactNode;
                                                                                                    • Custom renderer to transform an item into tag content.

                                                                                                    interface MultiSelectProps

                                                                                                    interface MultiSelectProps<T> extends ListItemsProps<T>, SelectPopoverProps {}

                                                                                                      property disabled

                                                                                                      disabled?: boolean;
                                                                                                      • Whether the component is non-interactive. If true, the list's item renderer will not be called.

                                                                                                        false

                                                                                                      property fill

                                                                                                      fill?: boolean;
                                                                                                      • Whether the component should take up the full width of its container.

                                                                                                      property menuProps

                                                                                                      menuProps?: React.HTMLAttributes<HTMLUListElement>;
                                                                                                      • Props to spread to the Menu listbox containing the selectable options.

                                                                                                      property onClear

                                                                                                      onClear?: () => void;
                                                                                                      • If provided, this component will render a "clear" button inside its TagInput. Clicking that button will invoke this callback to clear all items from the current selection.

                                                                                                      property onRemove

                                                                                                      onRemove?: (value: T, index: number) => void;
                                                                                                      • Callback invoked when an item is removed from the selection by removing its tag in the TagInput. This is generally more useful than tagInputProps.onRemove because it receives the removed value instead of the value's rendered ReactNode tag.

                                                                                                        It is not recommended to supply _both_ this prop and tagInputProps.onRemove.

                                                                                                      property openOnKeyDown

                                                                                                      openOnKeyDown?: boolean;
                                                                                                      • If true, the component waits until a keydown event in the TagInput before opening its popover.

                                                                                                        If false, the popover opens immediately after a mouse click focuses the component's TagInput.

                                                                                                        N.B. the behavior of this prop differs slightly from the same one in the Suggest component; see https://github.com/palantir/blueprint/issues/4152.

                                                                                                        false

                                                                                                      property placeholder

                                                                                                      placeholder?: string;
                                                                                                      • Input placeholder text. Shorthand for tagInputProps.placeholder.

                                                                                                        "Search..."

                                                                                                      property selectedItems

                                                                                                      selectedItems: T[];
                                                                                                      • Controlled selected values.

                                                                                                      property tagInputProps

                                                                                                      tagInputProps?: Partial<Omit<TagInputProps, 'inputValue' | 'onInputChange'>>;
                                                                                                      • Props to pass to the [TagInput component](##core/components/tag-input).

                                                                                                        Some properties are unavailable: - tagInputProps.inputValue: use query instead - tagInputProps.onInputChange: use onQueryChange instead

                                                                                                        Some properties are available, but discouraged. If you find yourself using these due to a bug in MultiSelect or some edge case which is not handled by onItemSelect, onItemsPaste, onRemove, and onClear, please file a bug in the Blueprint repo: - tagInputProps.onChange

                                                                                                        Notes for tagInputProps.rightElement: - you are responsible for disabling any elements you may render here when the overall MultiSelect is disabled - if the onClear prop is defined, this element will override/replace the default rightElement, which is a "clear" button that removes all items from the current selection.

                                                                                                      property tagRenderer

                                                                                                      tagRenderer: (item: T) => React.ReactNode;
                                                                                                      • Custom renderer to transform an item into tag content.

                                                                                                      interface OmnibarProps

                                                                                                      interface OmnibarProps<T> extends ListItemsProps<T> {}

                                                                                                        property inputProps

                                                                                                        inputProps?: InputGroupProps;
                                                                                                        • Props to spread to the query InputGroup. Use query and onQueryChange instead of inputProps.value and inputProps.onChange to control this input.

                                                                                                        property isOpen

                                                                                                        isOpen: boolean;
                                                                                                        • Toggles the visibility of the omnibar. This prop is required because the component is controlled.

                                                                                                        property onClose

                                                                                                        onClose?: (event?: React.SyntheticEvent<HTMLElement>) => void;
                                                                                                        • A callback that is invoked when user interaction causes the omnibar to close, such as clicking on the overlay or pressing the esc key (if enabled). Receives the event from the user's interaction, if there was an event (generally either a mouse or key event).

                                                                                                          Note that due to controlled usage, this component will not actually close itself until the isOpen prop becomes false. .

                                                                                                        property overlayProps

                                                                                                        overlayProps?: Partial<OverlayProps>;
                                                                                                        • Props to spread to Overlay.

                                                                                                        interface QueryListProps

                                                                                                        interface QueryListProps<T> extends ListItemsProps<T> {}

                                                                                                          property disabled

                                                                                                          disabled?: boolean;
                                                                                                          • Whether the list is disabled.

                                                                                                            false

                                                                                                          property initialActiveItem

                                                                                                          initialActiveItem?: T;
                                                                                                          • Initial active item, useful if the parent component is controlling its selectedItem but not activeItem.

                                                                                                          property menuProps

                                                                                                          menuProps?: React.HTMLAttributes<HTMLUListElement>;
                                                                                                          • Additional props to apply to the Menu that is created within the QueryList

                                                                                                          property onKeyDown

                                                                                                          onKeyDown?: React.KeyboardEventHandler<HTMLElement>;
                                                                                                          • Callback invoked when user presses a key, after processing QueryList's own key events (up/down to navigate active item). This callback is passed to renderer and (along with onKeyUp) can be attached to arbitrary content elements to support keyboard selection.

                                                                                                          property onKeyUp

                                                                                                          onKeyUp?: React.KeyboardEventHandler<HTMLElement>;
                                                                                                          • Callback invoked when user releases a key, after processing QueryList's own key events (enter to select active item). This callback is passed to renderer and (along with onKeyDown) can be attached to arbitrary content elements to support keyboard selection.

                                                                                                          property renderer

                                                                                                          renderer: (listProps: QueryListRendererProps<T>) => React.JSX.Element;
                                                                                                          • Customize rendering of the component. Receives an object with props that should be applied to elements as necessary.

                                                                                                          interface QueryListRendererProps

                                                                                                          interface QueryListRendererProps<T>
                                                                                                          extends Pick<QueryListState<T>, 'activeItem' | 'filteredItems' | 'query'>,
                                                                                                          Props {}
                                                                                                          • An object describing how to render a QueryList. A QueryList renderer receives this object as its sole argument.

                                                                                                          property handleItemSelect

                                                                                                          handleItemSelect: (item: T, event?: React.SyntheticEvent<HTMLElement>) => void;
                                                                                                          • Selection handler that should be invoked when a new item has been chosen, perhaps because the user clicked it.

                                                                                                          property handleKeyDown

                                                                                                          handleKeyDown: React.KeyboardEventHandler<HTMLElement>;
                                                                                                          • Keyboard handler for up/down arrow keys to shift the active item. Attach this handler to any element that should support this interaction.

                                                                                                          property handleKeyUp

                                                                                                          handleKeyUp: React.KeyboardEventHandler<HTMLElement>;
                                                                                                          • Keyboard handler for enter key to select the active item. Attach this handler to any element that should support this interaction.

                                                                                                          property handlePaste

                                                                                                          handlePaste: (queries: string[]) => void;
                                                                                                          • Handler that should be invoked when the user pastes one or more values.

                                                                                                            This callback will use itemPredicate with exactMatch=true to find a subset of items exactly matching the pasted values provided, then it will invoke onItemsPaste with those found items. Each pasted value that does not exactly match an item will be ignored.

                                                                                                            If creating items is enabled (by providing both createNewItemFromQuery and createNewItemRenderer), then pasted values that do not exactly match an existing item will emit a new item as created via createNewItemFromQuery.

                                                                                                            If itemPredicate returns multiple matching items for a particular query in queries, then only the first matching item will be emitted.

                                                                                                          property handleQueryChange

                                                                                                          handleQueryChange: React.ChangeEventHandler<HTMLInputElement>;
                                                                                                          • Change handler for query string. Attach this to an input element to allow QueryList to control the query.

                                                                                                          property itemList

                                                                                                          itemList: React.ReactNode;
                                                                                                          • Rendered elements returned from itemListRenderer prop.

                                                                                                          interface Select2Props

                                                                                                          interface SelectProps<T> extends ListItemsProps<T>, SelectPopoverProps {}

                                                                                                            property children

                                                                                                            children?: React.ReactNode;
                                                                                                            • Element which triggers the select popover. In most cases, you should display the name or label of the curently selected item here.

                                                                                                            property disabled

                                                                                                            disabled?: boolean;
                                                                                                            • Whether the component is non-interactive. If true, the list's item renderer will not be called. Note that you'll also need to disable the component's children, if appropriate.

                                                                                                              false

                                                                                                            property fill

                                                                                                            fill?: boolean;
                                                                                                            • Whether the component should take up the full width of its container. You also have to ensure that the child component has fill set to true or is styled appropriately.

                                                                                                            property filterable

                                                                                                            filterable?: boolean;
                                                                                                            • Whether the dropdown list can be filtered. Disabling this option will remove the InputGroup and ignore inputProps.

                                                                                                              true

                                                                                                            property inputProps

                                                                                                            inputProps?: Partial<Omit<InputGroupProps, 'value' | 'onChange'>>;
                                                                                                            • Props to pass to the query [InputGroup component](#core/components/input-group).

                                                                                                              Some properties are unavailable: - inputProps.value: use query instead - inputProps.onChange: use onQueryChange instead

                                                                                                            property menuProps

                                                                                                            menuProps?: React.HTMLAttributes<HTMLUListElement>;
                                                                                                            • HTML attributes to add to the Menu listbox containing the selectable options.

                                                                                                            property resetOnClose

                                                                                                            resetOnClose?: boolean;
                                                                                                            • Whether the active item should be reset to the first matching item _when the popover closes_. The query will also be reset to the empty string.

                                                                                                              false

                                                                                                            interface SelectPopoverProps

                                                                                                            interface SelectPopoverProps {}
                                                                                                            • Reusable collection of props for components in this package which render a Popover and need to provide some degree of customization for that popover.

                                                                                                            property popoverContentProps

                                                                                                            popoverContentProps?: React.HTMLAttributes<HTMLDivElement>;
                                                                                                            • HTML attributes to spread to the popover content container element.

                                                                                                            property popoverProps

                                                                                                            popoverProps?: Partial<
                                                                                                            Omit<PopoverProps, 'content' | 'defaultIsOpen' | 'fill' | 'renderTarget'>
                                                                                                            >;
                                                                                                            • Props to spread to the popover.

                                                                                                              Note that content cannot be changed, but you may apply some props to the content wrapper element with popoverContentProps. Likewise, targetProps is no longer supported as it was in Blueprint v4, but you may use popoverTargetProps instead.

                                                                                                              N.B. disabled is supported here, as this can be distinct from disabling the entire select button / input control element. There are some cases where we only want to disable the popover interaction.

                                                                                                            property popoverRef

                                                                                                            popoverRef?: React.RefObject<Popover<DefaultPopoverTargetHTMLProps>>;
                                                                                                            • Optional ref for the Popover component instance. This is sometimes useful to reposition the popover.

                                                                                                              Note that this is defined as a specific kind of Popover instance which should be compatible with most use cases, since it uses the default target props interface.

                                                                                                            property popoverTargetProps

                                                                                                            popoverTargetProps?: React.HTMLAttributes<HTMLElement>;
                                                                                                            • HTML attributes to add to the popover target element.

                                                                                                            interface SelectProps

                                                                                                            interface SelectProps<T> extends ListItemsProps<T>, SelectPopoverProps {}

                                                                                                              property children

                                                                                                              children?: React.ReactNode;
                                                                                                              • Element which triggers the select popover. In most cases, you should display the name or label of the curently selected item here.

                                                                                                              property disabled

                                                                                                              disabled?: boolean;
                                                                                                              • Whether the component is non-interactive. If true, the list's item renderer will not be called. Note that you'll also need to disable the component's children, if appropriate.

                                                                                                                false

                                                                                                              property fill

                                                                                                              fill?: boolean;
                                                                                                              • Whether the component should take up the full width of its container. You also have to ensure that the child component has fill set to true or is styled appropriately.

                                                                                                              property filterable

                                                                                                              filterable?: boolean;
                                                                                                              • Whether the dropdown list can be filtered. Disabling this option will remove the InputGroup and ignore inputProps.

                                                                                                                true

                                                                                                              property inputProps

                                                                                                              inputProps?: Partial<Omit<InputGroupProps, 'value' | 'onChange'>>;
                                                                                                              • Props to pass to the query [InputGroup component](#core/components/input-group).

                                                                                                                Some properties are unavailable: - inputProps.value: use query instead - inputProps.onChange: use onQueryChange instead

                                                                                                              property menuProps

                                                                                                              menuProps?: React.HTMLAttributes<HTMLUListElement>;
                                                                                                              • HTML attributes to add to the Menu listbox containing the selectable options.

                                                                                                              property resetOnClose

                                                                                                              resetOnClose?: boolean;
                                                                                                              • Whether the active item should be reset to the first matching item _when the popover closes_. The query will also be reset to the empty string.

                                                                                                                false

                                                                                                              interface Suggest2Props

                                                                                                              interface SuggestProps<T>
                                                                                                              extends ListItemsProps<T>,
                                                                                                              Omit<SelectPopoverProps, 'popoverTargetProps'> {}

                                                                                                                property closeOnSelect

                                                                                                                closeOnSelect?: boolean;
                                                                                                                • Whether the popover should close after selecting an item.

                                                                                                                  true

                                                                                                                property defaultSelectedItem

                                                                                                                defaultSelectedItem?: T;
                                                                                                                • The uncontrolled default selected item. This prop is ignored if selectedItem is used to control the state.

                                                                                                                property disabled

                                                                                                                disabled?: boolean;
                                                                                                                • Whether the input field should be disabled.

                                                                                                                property fill

                                                                                                                fill?: boolean;
                                                                                                                • Whether the component should take up the full width of its container.

                                                                                                                property inputProps

                                                                                                                inputProps?: Partial<
                                                                                                                Omit<InputGroupProps, 'disabled' | 'fill' | 'value' | 'onChange'>
                                                                                                                >;
                                                                                                                • Props to pass to the query [InputGroup component](#core/components/input-group).

                                                                                                                  Some properties are unavailable: - inputProps.value: use query instead - inputProps.onChange: use onQueryChange instead - inputProps.disabled: use disabled instead - inputProps.fill: use fill instead

                                                                                                                  Other notes: - inputProps.tagName will override popoverProps.targetTagName - inputProps.className will work as expected, but this is redundant with the simpler className prop

                                                                                                                property inputValueRenderer

                                                                                                                inputValueRenderer: (item: T) => string;
                                                                                                                • Custom renderer to transform an item into a string for the input value.

                                                                                                                property menuProps

                                                                                                                menuProps?: React.HTMLAttributes<HTMLUListElement>;
                                                                                                                • HTML attributes to add to the Menu listbox containing the selectable options.

                                                                                                                property openOnKeyDown

                                                                                                                openOnKeyDown?: boolean;
                                                                                                                • If true, the component waits until a keydown event in the TagInput before opening its popover.

                                                                                                                  If false, the popover opens immediately after a mouse click or TAB key interaction focuses the component's TagInput.

                                                                                                                  false

                                                                                                                property resetOnClose

                                                                                                                resetOnClose?: boolean;
                                                                                                                • Whether the active item should be reset to the first matching item _when the popover closes_. The query will also be reset to the empty string.

                                                                                                                  false

                                                                                                                property selectedItem

                                                                                                                selectedItem?: T | null;
                                                                                                                • The currently selected item, or null to indicate that no item is selected. If omitted or undefined, this prop will be uncontrolled (managed by the component's state). Use onItemSelect to listen for updates.

                                                                                                                interface SuggestProps

                                                                                                                interface SuggestProps<T>
                                                                                                                extends ListItemsProps<T>,
                                                                                                                Omit<SelectPopoverProps, 'popoverTargetProps'> {}

                                                                                                                  property closeOnSelect

                                                                                                                  closeOnSelect?: boolean;
                                                                                                                  • Whether the popover should close after selecting an item.

                                                                                                                    true

                                                                                                                  property defaultSelectedItem

                                                                                                                  defaultSelectedItem?: T;
                                                                                                                  • The uncontrolled default selected item. This prop is ignored if selectedItem is used to control the state.

                                                                                                                  property disabled

                                                                                                                  disabled?: boolean;
                                                                                                                  • Whether the input field should be disabled.

                                                                                                                  property fill

                                                                                                                  fill?: boolean;
                                                                                                                  • Whether the component should take up the full width of its container.

                                                                                                                  property inputProps

                                                                                                                  inputProps?: Partial<
                                                                                                                  Omit<InputGroupProps, 'disabled' | 'fill' | 'value' | 'onChange'>
                                                                                                                  >;
                                                                                                                  • Props to pass to the query [InputGroup component](#core/components/input-group).

                                                                                                                    Some properties are unavailable: - inputProps.value: use query instead - inputProps.onChange: use onQueryChange instead - inputProps.disabled: use disabled instead - inputProps.fill: use fill instead

                                                                                                                    Other notes: - inputProps.tagName will override popoverProps.targetTagName - inputProps.className will work as expected, but this is redundant with the simpler className prop

                                                                                                                  property inputValueRenderer

                                                                                                                  inputValueRenderer: (item: T) => string;
                                                                                                                  • Custom renderer to transform an item into a string for the input value.

                                                                                                                  property menuProps

                                                                                                                  menuProps?: React.HTMLAttributes<HTMLUListElement>;
                                                                                                                  • HTML attributes to add to the Menu listbox containing the selectable options.

                                                                                                                  property openOnKeyDown

                                                                                                                  openOnKeyDown?: boolean;
                                                                                                                  • If true, the component waits until a keydown event in the TagInput before opening its popover.

                                                                                                                    If false, the popover opens immediately after a mouse click or TAB key interaction focuses the component's TagInput.

                                                                                                                    false

                                                                                                                  property resetOnClose

                                                                                                                  resetOnClose?: boolean;
                                                                                                                  • Whether the active item should be reset to the first matching item _when the popover closes_. The query will also be reset to the empty string.

                                                                                                                    false

                                                                                                                  property selectedItem

                                                                                                                  selectedItem?: T | null;
                                                                                                                  • The currently selected item, or null to indicate that no item is selected. If omitted or undefined, this prop will be uncontrolled (managed by the component's state). Use onItemSelect to listen for updates.

                                                                                                                  Type Aliases

                                                                                                                  type ItemListPredicate

                                                                                                                  type ItemListPredicate<T> = (query: string, items: T[]) => T[];
                                                                                                                  • A custom predicate for returning an entirely new items array based on the provided query. See usage sites in ListItemsProps.

                                                                                                                  type ItemListRenderer

                                                                                                                  type ItemListRenderer<T> = (
                                                                                                                  itemListProps: ItemListRendererProps<T>
                                                                                                                  ) => React.JSX.Element | null;
                                                                                                                  • Type alias for a function that renders the list of items.

                                                                                                                  type ItemPredicate

                                                                                                                  type ItemPredicate<T> = (
                                                                                                                  query: string,
                                                                                                                  item: T,
                                                                                                                  index?: number,
                                                                                                                  exactMatch?: boolean
                                                                                                                  ) => boolean;
                                                                                                                  • A custom predicate for filtering items based on the provided query. See usage sites in ListItemsProps.

                                                                                                                  type ItemRenderer

                                                                                                                  type ItemRenderer<T> = (
                                                                                                                  item: T,
                                                                                                                  itemProps: ItemRendererProps
                                                                                                                  ) => React.JSX.Element | null;
                                                                                                                  • Type alias for a function that receives an item and props and renders a JSX element (or null).

                                                                                                                    T list item data type

                                                                                                                  type ItemsEqualComparator

                                                                                                                  type ItemsEqualComparator<T> = (itemA: T, itemB: T) => boolean;
                                                                                                                  • Equality test comparator to determine if two ListItemsProps items are equivalent.

                                                                                                                    true if the two items are equivalent.

                                                                                                                  type ItemsEqualProp

                                                                                                                  type ItemsEqualProp<T> = ItemsEqualComparator<T> | keyof T;

                                                                                                                  Namespaces

                                                                                                                  namespace Classes

                                                                                                                  module 'lib/esm/common/classes.d.ts' {}

                                                                                                                    variable MULTISELECT

                                                                                                                    const MULTISELECT: string;

                                                                                                                      variable MULTISELECT_POPOVER

                                                                                                                      const MULTISELECT_POPOVER: string;

                                                                                                                        variable MULTISELECT_TAG_INPUT_INPUT

                                                                                                                        const MULTISELECT_TAG_INPUT_INPUT: string;

                                                                                                                          variable OMNIBAR

                                                                                                                          const OMNIBAR: string;

                                                                                                                            variable OMNIBAR_OVERLAY

                                                                                                                            const OMNIBAR_OVERLAY: string;

                                                                                                                              variable SELECT_POPOVER

                                                                                                                              const SELECT_POPOVER: string;

                                                                                                                                variable SUGGEST_POPOVER

                                                                                                                                const SUGGEST_POPOVER: string;

                                                                                                                                  Package Files (13)

                                                                                                                                  Dependencies (4)

                                                                                                                                  Dev Dependencies (11)

                                                                                                                                  Peer Dependencies (3)

                                                                                                                                  Badge

                                                                                                                                  To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

                                                                                                                                  You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@blueprintjs/select.

                                                                                                                                  • Markdown
                                                                                                                                    [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/@blueprintjs/select)
                                                                                                                                  • HTML
                                                                                                                                    <a href="https://www.jsdocs.io/package/@blueprintjs/select"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>