tessl/npm-blueprintjs--select

Components related to selecting items from a list

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Blueprint Select

Name: tessl/npm-blueprintjs--select
Author: tessl

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

Workspace: tessl
Visibility: Public
Created: 6 months ago
Last updated: about 2 months ago
Describes: pkg:npm/@blueprintjs/select@6.0.x
Publish Source: CLI
Badge