or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdmulti-select.mdomnibar.mdquery-list.mdselect.mdsuggest.mdutilities.md
tile.json

tessl/npm-blueprintjs--select

Components related to selecting items from a list

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@blueprintjs/select@6.0.x

To install, run

npx @tessl/cli install tessl/npm-blueprintjs--select@6.0.0

index.mddocs/

Blueprint Select

Blueprint Select is a comprehensive React component library that provides sophisticated selection interfaces for web applications. It offers five main components for different selection patterns: single item selection (Select), typeahead/autocomplete (Suggest), multiple item selection (MultiSelect), spotlight-style search (Omnibar), and a flexible query management system (QueryList).

Package Information

  • Package Name: @blueprintjs/select
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @blueprintjs/select @blueprintjs/core @blueprintjs/icons react react-dom

Core Imports

import { Select, MultiSelect, Suggest, Omnibar, QueryList } from "@blueprintjs/select";

For CommonJS:

const { Select, MultiSelect, Suggest, Omnibar, QueryList } = require("@blueprintjs/select");

Basic Usage

import React from "react";
import { Select, ItemRenderer } from "@blueprintjs/select";

interface Film {
  title: string;
  year: number;
  rank: number;
}

const films: Film[] = [
  { title: "The Shawshank Redemption", year: 1994, rank: 1 },
  { title: "The Godfather", year: 1972, rank: 2 },
  { title: "The Dark Knight", year: 2008, rank: 3 },
];

const renderFilm: ItemRenderer<Film> = (film, { handleClick, modifiers }) => (
  <div
    onClick={handleClick}
    style={{
      padding: "8px",
      background: modifiers.active ? "#137cbd" : "transparent",
      color: modifiers.active ? "white" : "black",
    }}
  >
    {film.title} ({film.year})
  </div>
);

const FilmSelect = () => (
  <Select<Film>
    items={films}
    itemRenderer={renderFilm}
    onItemSelect={(film) => console.log("Selected:", film.title)}
    noResults={<div>No films found.</div>}
  >
    <button>Select a film...</button>
  </Select>
);

Architecture

Blueprint Select is built around several key concepts:

  • Generic Type Support: All components support generic type parameters for item types
  • Consistent API: Shared interfaces and patterns across all selection components
  • QueryList Foundation: All components build upon the foundational QueryList component
  • Customizable Rendering: Flexible renderer props for items, lists, and popovers
  • Keyboard Navigation: Full keyboard accessibility with arrow keys, Enter, and Escape
  • Blueprint Integration: Seamless integration with Blueprint's design system and core components

Capabilities

Single Item Selection

Select component for choosing one item from a dropdown list with optional filtering.

class Select<T> extends React.Component<SelectProps<T>, SelectState> {
  static ofType<U>(): new (props: SelectProps<U>) => Select<U>;
}

interface SelectProps<T> extends ListItemsProps<T>, SelectPopoverProps {
  children?: React.ReactNode;
  disabled?: boolean;
  fill?: boolean;
  filterable?: boolean;
  inputProps?: Partial<InputGroupProps>;
  menuProps?: React.HTMLAttributes<HTMLUListElement>;
  placeholder?: string;
  resetOnClose?: boolean;
}

Single Item Selection

Multiple Item Selection

MultiSelect component for choosing multiple items with tag-based display.

class MultiSelect<T> extends React.Component<MultiSelectProps<T>, MultiSelectState> {
  static ofType<U>(): new (props: MultiSelectProps<U>) => MultiSelect<U>;
}

interface MultiSelectProps<T> extends ListItemsProps<T>, SelectPopoverProps {
  selectedItems: T[];
  tagRenderer: (item: T) => React.ReactNode;
  customTarget?: (selectedItems: T[], isOpen: boolean) => React.ReactNode;
  disabled?: boolean;
  fill?: boolean;
  onClear?: () => void;
  onRemove?: (value: T, index: number) => void;
  openOnKeyDown?: boolean;
  placeholder?: string;
}

Multiple Item Selection

Typeahead Input

Suggest component for text input with autocomplete suggestions.

class Suggest<T> extends React.Component<SuggestProps<T>, SuggestState<T>> {
  static ofType<U>(): new (props: SuggestProps<U>) => Suggest<U>;
}

interface SuggestProps<T> extends ListItemsProps<T>, Omit<SelectPopoverProps, "popoverTargetProps"> {
  inputValueRenderer: (item: T) => string;
  selectedItem?: T | null;
  defaultSelectedItem?: T;
  closeOnSelect?: boolean;
  disabled?: boolean;
  fill?: boolean;
  inputProps?: Partial<Omit<InputGroupProps, "disabled" | "fill" | "value" | "onChange">>;
  menuProps?: React.HTMLAttributes<HTMLUListElement>;
  openOnKeyDown?: boolean;
  resetOnClose?: boolean;
}

Typeahead Input

Spotlight Search

Omnibar component providing macOS Spotlight-style search overlay.

class Omnibar<T> extends React.Component<OmnibarProps<T>> {
  static ofType<U>(): new (props: OmnibarProps<U>) => Omnibar<U>;
}

interface OmnibarProps<T> extends ListItemsProps<T> {
  isOpen: boolean;
  onClose?: (event?: React.SyntheticEvent<HTMLElement>) => void;
  inputProps?: InputGroupProps;
  overlayProps?: Partial<OverlayProps>;
}

Spotlight Search

Query Management

QueryList higher-order component for managing query interactions with item lists.

class QueryList<T> extends React.Component<QueryListProps<T>, QueryListState<T>> {
  static ofType<U>(): new (props: QueryListProps<U>) => QueryList<U>;
  
  scrollActiveItemIntoView(): void;
  setQuery(query: string, resetActiveItem?: boolean): void;
  setActiveItem(activeItem: T | null): void;
}

interface QueryListProps<T> extends ListItemsProps<T> {
  renderer: (listProps: QueryListRendererProps<T>) => React.JSX.Element;
  initialActiveItem?: T;
  disabled?: boolean;
}

Query Management

Core Types

Item Rendering

type ItemRenderer<T> = (item: T, itemProps: ItemRendererProps) => React.JSX.Element | null;

interface ItemRendererProps<T extends HTMLElement = HTMLLIElement> {
  ref?: React.Ref<T>;
  handleClick: React.MouseEventHandler<HTMLElement>;
  handleFocus?: () => void;
  index: number;
  modifiers: ItemModifiers;
  query: string;
}

interface ItemModifiers {
  active: boolean;
  disabled: boolean;
  matchesPredicate: boolean;
}

Item Filtering

type ItemPredicate<T> = (query: string, item: T, index?: number, exactMatch?: boolean) => boolean;
type ItemListPredicate<T> = (query: string, items: T[]) => T[];

Common Props

interface ListItemsProps<T> {
  items: T[];
  itemRenderer: ItemRenderer<T>;
  onItemSelect: (item: T, event?: React.SyntheticEvent<HTMLElement>) => void;
  activeItem?: T | CreateNewItem | null;
  itemPredicate?: ItemPredicate<T>;
  itemListPredicate?: ItemListPredicate<T>;
  itemsEqual?: ItemsEqualProp<T>;
  itemDisabled?: keyof T | ((item: T, index: number) => boolean);
  itemListRenderer?: ItemListRenderer<T>;
  initialContent?: React.ReactNode | null;
  noResults?: React.ReactNode;
  onActiveItemChange?: (activeItem: T | null, isCreateNewItem: boolean) => void;
  onItemsPaste?: (items: T[]) => void;
  onQueryChange?: (query: string, event?: React.ChangeEvent<HTMLInputElement>) => void;
  createNewItemFromQuery?: (query: string) => T | T[];
  createNewItemRenderer?: (query: string, active: boolean, handleClick: React.MouseEventHandler<HTMLElement>) => React.JSX.Element | undefined;
  createNewItemPosition?: "first" | "last";
  query?: string;
  resetOnQuery?: boolean;
  resetOnSelect?: boolean;
  scrollToActiveItem?: boolean;
}

type ItemsEqualProp<T> = ItemsEqualComparator<T> | keyof T;
type ItemsEqualComparator<T> = (itemA: T, itemB: T) => boolean;

Utilities

Common Utilities