Suggest

Suggest picks one item from a list by typing. It renders a text input instead of a button, so it suits users who know what they want.

Usage#

import { Suggest } from "@clawscale/react/select";

Suggest takes the shared item props, plus inputValueRenderer.

Examples#

Basic#

inputValueRenderer turns the selected item into the input text. It is required. Pass selectedItem to control the choice, or leave it out to let Suggest keep it.

select/suggest/basic.tsx

import { MenuItem } from "@clawscale/react";
import { type ItemRenderer, Suggest } from "@clawscale/react/select";
import { useState } from "react";
import { DATASETS, type Dataset, filterDataset } from "../_data";

const renderDataset: ItemRenderer<Dataset> = (dataset, { handleClick, handleFocus, id, modifiers, ref }) => {
  if (!modifiers.matchesPredicate) return null;
  return (
    <MenuItem
      key={dataset.id}
      ref={ref}
      id={id}
      active={modifiers.active}
      disabled={modifiers.disabled}
      label={dataset.owner}
      onClick={handleClick}
      onFocus={handleFocus}
      roleStructure="listoption"
      text={dataset.name}
    />
  );
};

export default function SuggestBasic() {
  const [dataset, setDataset] = useState<Dataset | null>(null);
  return (
    <Suggest<Dataset>
      items={DATASETS}
      itemPredicate={filterDataset}
      itemRenderer={renderDataset}
      inputProps={{ placeholder: "Search datasets" }}
      inputValueRenderer={(item) => item.name}
      noResults={<MenuItem disabled text="No datasets match." roleStructure="listoption" />}
      onItemSelect={setDataset}
      selectedItem={dataset}
    />
  );
}

Input value#

The input can show more than the list does. Here it shows the qualified name, owner.name.

select/suggest/input-value.tsx

import { Suggest } from "@clawscale/react/select";
import { useState } from "react";
import { DATASETS, type Dataset, filterDataset } from "../_data";
import { renderDataset } from "../_renderers";

export default function SuggestInputValue() {
  const [dataset, setDataset] = useState(() => DATASETS.find((item) => item.name === "orders_daily") ?? null);
  return (
    <Suggest<Dataset>
      items={DATASETS}
      itemPredicate={filterDataset}
      itemRenderer={renderDataset}
      inputValueRenderer={(item) => `${item.owner}.${item.name}`}
      onItemSelect={setDataset}
      selectedItem={dataset}
    />
  );
}

Close on select#

closeOnSelect={false} keeps the list open after a pick, so users can try several items in a row.

select/suggest/close-on-select.tsx

import { Suggest } from "@clawscale/react/select";
import { useState } from "react";
import { DATASETS, type Dataset, filterDataset } from "../_data";
import { renderDataset } from "../_renderers";

export default function SuggestCloseOnSelect() {
  const [dataset, setDataset] = useState<Dataset | null>(null);
  return (
    <Suggest<Dataset>
      closeOnSelect={false}
      items={DATASETS}
      itemPredicate={filterDataset}
      itemRenderer={renderDataset}
      inputProps={{ placeholder: "Compare datasets" }}
      inputValueRenderer={(item) => item.name}
      onItemSelect={setDataset}
      selectedItem={dataset}
    />
  );
}

Reset on close#

resetOnClose clears the query and the active item when the list closes. Type part of a name, then click away: the input empties instead of keeping the partial query.

select/suggest/reset-on-close.tsx

import { Suggest } from "@clawscale/react/select";
import { useState } from "react";
import { DATASETS, type Dataset, filterDataset } from "../_data";
import { renderDataset } from "../_renderers";

export default function SuggestResetOnClose() {
  const [dataset, setDataset] = useState<Dataset | null>(null);
  return (
    <Suggest<Dataset>
      items={DATASETS}
      itemPredicate={filterDataset}
      itemRenderer={renderDataset}
      inputProps={{ placeholder: "Search datasets" }}
      inputValueRenderer={(item) => item.name}
      onItemSelect={setDataset}
      resetOnClose
      selectedItem={dataset}
    />
  );
}

Props interface#

interface SuggestProps extends ListItemsProps<T>, Omit<SelectPopoverProps, "popoverTargetProps">@clawscale/react/select

Props	Description
`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. Inherited from `ListItemsProps`
`className`	`string` A space-delimited list of class names to pass along to a child element. Inherited from `Props`
`closeOnSelect`	`boolean` = `true` Whether the popover should close after selecting an item.
`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. Inherited from `ListItemsProps`
`createNewItemPosition`	`"first" \| "last"` = `'last'` Determines the position of the `createNewItem` within the list: first or last. Only relevant when `createNewItemRenderer` is defined. Inherited from `ListItemsProps`
`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. Inherited from `ListItemsProps`
`defaultSelectedItem`	`T` The uncontrolled default selected item. This prop is ignored if `selectedItem` is used to control the state.
`disabled`	`boolean` Whether the input field should be disabled.
`fill`	`boolean` Whether the component should take up the full width of its container.
`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. Inherited from `ListItemsProps`
`inputProps`	`Partial<Omit<InputGroupProps, "disabled" \| "fill" \| "value" \| "onChange">>` Props to pass to the query InputGroup component.
`inputValueRenderer`required	`(item: T) => string` Custom renderer to transform an item into a string for the input value.
`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. Inherited from `ListItemsProps`
`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.) Inherited from `ListItemsProps`
`itemListRenderer`	`ItemListRenderer<T>` Custom renderer for the contents of the dropdown. Inherited from `ListItemsProps`
`itemPredicate`	`ItemPredicate<T>` Customize querying of individual items. Inherited from `ListItemsProps`
`itemRenderer`required	`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. Inherited from `ListItemsProps`
`items`required	`T[]` Array of items in the list. Inherited from `ListItemsProps`
`itemsEqual`	`ItemsEqualProp<T>` Specifies how to test if two items are equal. By default, simple strict equality (`===`) is used to compare two items. Inherited from `ListItemsProps`
`menuProps`	`React.HTMLAttributes<HTMLUListElement>` HTML attributes to add to the `Menu` listbox containing the selectable options.
`noResults`	`React.ReactNode` React content to render when filtering items returns zero results. If omitted, nothing will be rendered in this case. Inherited from `ListItemsProps`
`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. Inherited from `ListItemsProps`
`onItemSelect`required	`(item: T, event?: React.SyntheticEvent<HTMLElement>) => void` Callback invoked when an item from the list is selected, typically by clicking or pressing `enter` key. Inherited from `ListItemsProps`
`onItemsPaste`	`(items: T[]) => void` Callback invoked when multiple items are selected at once via pasting. Inherited from `ListItemsProps`
`onQueryChange`	`(query: string, event?: React.ChangeEvent<HTMLInputElement>) => void` Callback invoked when the query string changes. Inherited from `ListItemsProps`
`openOnKeyDown`	`boolean` = `false` If true, the component waits until a keydown event in the TagInput before opening its popover.
`popoverContentProps`	`React.HTMLAttributes<HTMLDivElement>` HTML attributes to spread to the popover content container element. Inherited from `SelectPopoverProps`
`popoverProps`	`Partial<Omit<PopoverProps, "content" \| "defaultIsOpen" \| "fill" \| "renderTarget">>` Props to spread to the popover. Inherited from `SelectPopoverProps`
`popoverRef`	`React.RefObject<PopoverNextRef>` Optional ref to the popover. `popoverRef.current?.reposition()` re-runs position calculation, useful when the target moves in a way the popover doesn't observe automatically (e.g. a parent layout change that doesn't trigger a resize). Inherited from `SelectPopoverProps`
`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. Inherited from `ListItemsProps`
`resetOnClose`	`boolean` = `false` 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.
`resetOnQuery`	`boolean` = `true` Whether the active item should be reset to the first matching item _every time the query changes_ (via prop or by user input). Inherited from `ListItemsProps`
`resetOnSelect`	`boolean` = `false` 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. Inherited from `ListItemsProps`
`scrollToActiveItem`	`boolean` = `true` 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). Inherited from `ListItemsProps`
`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.