Query list

QueryList holds the query, filtering and keyboard logic behind every component in the package, and renders nothing itself. Use it to build a picker that the other components do not cover.

Usage#

import { QueryList, renderFilteredItems } from "@clawscale/react/select";

QueryList takes the shared item props, plus a required renderer.

Examples#

Custom list renderer#

This picker renders inline instead of in a popover.

renderer lays out the whole component. It receives the query, the rendered list and the key handlers. Attach handleKeyDown and handleKeyUp to a wrapper, so the arrow keys and Enter work from the input.
itemListRenderer replaces the default list. Here it adds a summary line above the options. Attach itemsParentRef to the element that holds the options, so the active option scrolls into view.
renderFilteredItems renders the matching items, or its second argument when nothing matches.
listId fixes the id of the list. Without it, QueryList generates one, and server and client renders can disagree.

12 of 12 datasets, 8.6B rows

select/query-list/custom-renderer.tsx

import { Card, Classes, InputGroup, Menu, MenuItem } from "@clawscale/react";
import { type ItemListRenderer, QueryList, renderFilteredItems } from "@clawscale/react/select";
import { useState } from "react";
import { DATASETS, type Dataset, filterDataset, formatRows } from "../_data";
import { renderCheckedDataset } from "../_renderers";

const scrollable = { maxHeight: 216, overflowY: "auto" } as const;

const renderList: ItemListRenderer<Dataset> = (list) => {
  const rows = list.filteredItems.reduce((sum, dataset) => sum + dataset.rows, 0);
  return (
    <>
      <div className={Classes.TEXT_MUTED} style={{ margin: "12px 4px 4px" }}>
        {list.filteredItems.length} of {list.items.length} datasets, {formatRows(rows)} rows
      </div>
      <Menu aria-label="Datasets" role="listbox" ulRef={list.itemsParentRef} {...list.menuProps} style={scrollable}>
        {renderFilteredItems(list, <MenuItem disabled text="No datasets match." roleStructure="listoption" />)}
      </Menu>
    </>
  );
};

export default function QueryListCustomRenderer() {
  const [dataset, setDataset] = useState<Dataset>();
  return (
    <QueryList<Dataset>
      items={DATASETS}
      itemPredicate={filterDataset}
      itemRenderer={renderCheckedDataset(dataset ? [dataset] : [])}
      itemListRenderer={renderList}
      listId="dataset-browser"
      onItemSelect={setDataset}
      renderer={(props) => (
        <Card compact onKeyDown={props.handleKeyDown} onKeyUp={props.handleKeyUp} style={{ width: 340 }}>
          <InputGroup
            aria-activedescendant={props.activeItemId}
            aria-label="Filter datasets"
            aria-controls={props.listId}
            leftIcon="search"
            placeholder="Filter datasets"
            value={props.query}
            onChange={props.handleQueryChange}
          />
          {props.itemList}
        </Card>
      )}
    />
  );
}

Props interface#

interface QueryListProps extends ListItemsProps<T>@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`
`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`
`disabled`	`boolean` = `false` Whether the list is disabled.
`initialActiveItem`	`T` Initial active item, useful if the parent component is controlling its selectedItem but not activeItem.
`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`
`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`
`listId`	`string` ID prefix for generating unique IDs for list options. Defaults to a generated ID.
`menuProps`	`React.HTMLAttributes<HTMLUListElement>` Additional props to apply to the `Menu` that is created within the `QueryList`
`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`
`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.
`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.
`onQueryChange`	`(query: string, event?: React.ChangeEvent<HTMLInputElement>) => void` Callback invoked when the query string changes. Inherited from `ListItemsProps`
`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`
`renderer`required	`(listProps: QueryListRendererProps<T>) => React.JSX.Element` Customize rendering of the component. Receives an object with props that should be applied to elements as necessary.
`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`

Renderer props#

renderer receives these props.

interface QueryListRendererProps extends Pick<QueryListState<T>, "activeItem" | "filteredItems" | "query">, Props@clawscale/react/select

An object describing how to render a QueryList. A QueryList renderer receives this object as its sole argument.

Props	Description
`activeItem`required	`T \| CreateNewItem \| null` The currently focused item (for keyboard interactions). Inherited from `QueryListState`
`activeItemId`	`string` ID of the currently active item for aria-activedescendant.
`className`	`string` A space-delimited list of class names to pass along to a child element. Inherited from `Props`
`filteredItems`required	`T[]` The original `items` array filtered by `itemListPredicate` or `itemPredicate`. Inherited from `QueryListState`
`handleItemSelect`required	`(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.
`handleKeyDown`required	`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.
`handleKeyUp`required	`React.KeyboardEventHandler<HTMLElement>` Keyboard handler for enter key to select the active item. Attach this handler to any element that should support this interaction.
`handlePaste`required	`(queries: string[]) => void` Handler that should be invoked when the user pastes one or more values.
`handleQueryChange`required	`React.ChangeEventHandler<HTMLInputElement>` Change handler for query string. Attach this to an input element to allow `QueryList` to control the query.
`itemList`required	`React.ReactNode` Rendered elements returned from `itemListRenderer` prop.
`listId`required	`string` ID of the list container for ARIA relationships.
`query`required	`string` The current query string. Inherited from `QueryListState`

Item list renderer props#

itemListRenderer receives these props.

interface ItemListRendererProps@clawscale/react/select

An object describing how to render the list of items. An itemListRenderer receives this object as its sole argument.

Props	Description
`activeItem`required	`T \| CreateNewItem \| null` The currently focused item (for keyboard interactions), or `null` to indicate that no item is active.
`filteredItems`required	`T[]` Array of items filtered by `itemListPredicate` or `itemPredicate`. See `items` for the full list of items.
`items`required	`T[]` Array of all items in the list. See `filteredItems` for a filtered array based on `query` and predicate props.
`itemsParentRef`required	`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.
`menuProps`	`React.HTMLAttributes<HTMLUListElement>` Props to apply to the `Menu` created within the `itemListRenderer`
`query`required	`string` The current query string.
`renderCreateItem`required	`() => React.JSX.Element \| null \| undefined` Call this function to render the "create new item" view component.
`renderItem`required	`(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.