Select

Introduction

Use Select<T> for choosing one item from a list. The component's children will be wrapped in a Popover that contains the list and an optional InputGroup to filter it. Provide a predicate to customize the filtering algorithm. The value of a Select<T> (the currently chosen item) is uncontrolled: listen to changes with onItemSelect.

Included Components

  1. Select: menu from which you can choose one option
  2. ItemRenderer: component to render each option in the select list
  3. ItemListRenderer: component to control how entire menu is rendered

Examples

Usage

Select

import React from "react";
import { Button, MenuItem, Select, ItemRenderer } from "@commure/components-foundation";
function MySelect() {
const colors = [ "red", "blue", "green", "purple" ];
// Select<T> is a generic component to work with your data types.
// In this case, the color items are of type string.
// In TypeScript, you must first obtain a non-generic reference:
const ColorSelect = Select.ofType<string>();
const renderColor: ItemRenderer<colors> = (color, { handleClick, modifiers }) => (
<MenuItem
active={modifiers.active}
key={color}
onClick={handleClick}
text={color}
/>
);
return (
<ColorSelect itemRenderer={renderColor} items={colors}>
{/* children become the popover target; render value here */}
<Button text="select me" rightIcon="double-caret-vertical" />
</ColorSelect>
);
}
export default ColorSelect;

API Reference

Select

Prop NameRequired?TypeDescription
activeItemfalseT | ICreateNewItem | nullThe 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.
createNewItemFromQueryfalse(query: string) => TIf provided, allows new items to be created using the current query string. This is invoked when user interaction causes a new item to be created, either by pressing the `Enter` key or by clicking on the "Create Item" option. It transforms a query string into an item type.
createNewItemRendererfalse(query: string, active: boolean, handleClick: React.MouseEventHandler<HTMLElement>) => Element | undefinedCustom 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.
disabledfalsebooleanWhether the component is non-interactive. Note that you'll also need to disable the component's children, if appropriate.
filterablefalsebooleanWhether the dropdown list can be filtered. Disabling this option will remove the `InputGroup` and ignore `inputProps`.
initialContentfalseReact.ReactNode | nullReact 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.
inputPropsfalseIInputGroupProps & HTMLInputPropsProps to spread to the query `InputGroup`. Use `query` and `onQueryChange` instead of `inputProps.value` and `inputProps.onChange` to control this input.
itemDisabledfalsekeyof T | (item: T, index: number) => booleanDetermine 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.
itemListPredicatefalseItemListPredicate<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.
itemListRendererfalseItemListRenderer<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.
itemPredicatefalseItemPredicate<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.
itemRenderertrueItemRenderer<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.
itemstrueT[]Array of items in the list.
itemsEqualfalseItemsEqualProp<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.
noResultsfalseReact.ReactNodeReact 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.
onActiveItemChangefalse(activeItem: T | null, isCreateNewItem: boolean) => voidInvoked 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 `ICreateNewItem` object to the `activeItem` _prop_ in order for the "Create Item" option to appear as active. __Note:__ You can instantiate a `ICreateNewItem` object using the `getCreateNewItem()` utility exported from this package.
onItemSelecttrue(item: T, event?: SyntheticEvent<HTMLElement>) => voidCallback invoked when an item from the list is selected, typically by clicking or pressing `enter` key.
onItemsPastefalse(items: T[]) => voidCallback invoked when multiple items are selected at once via pasting.
onQueryChangefalse(query: string, event?: ChangeEvent<HTMLInputElement>) => voidCallback invoked when the query string changes.
popoverPropsfalsePartial<IPopoverProps> & objectProps to spread to `Popover`. Note that `content` cannot be changed.
queryfalsestringQuery 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.
resetOnClosefalsebooleanWhether 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.
resetOnQueryfalsebooleanWhether the active item should be reset to the first matching item _every time the query changes_ (via prop or by user input).
resetOnSelectfalsebooleanWhether 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.
scrollToActiveItemfalsebooleanWhen `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).

Related Reading

Blueprint Select Reference
Blueprint Select Item Renderer
Blueprint Select Item List Renderer