Skip to content
ilinxa/pro-ui

Entity Picker

alphav0.2.0

Searchable picker for typed entities — single or multi select, kind badges, chip cluster with removal, and custom render slots.

Category: FormsUpdated: 2026-10-26Created: 2026-04-29Author: ilinxa

Context

Tier 1 pro-component for the graph-system. Generic over the entity type via `<EntityPicker<T extends EntityLike>>` with mode-aware `value` typing via TypeScript function overloads. Built on shadcn `Command` (cmdk) for search and `Popover` for the dropdown. Composed inside force-graph from v0.3 onward (linking-mode UI) and inside properties-form custom field renderers. Generic standalone: any 'pick one or more typed things' surface. cmdk's a11y wiring + keyboard nav (↑/↓/Enter/Esc) is inherited; multi-mode adds chips with per-chip remove buttons + Backspace-on-empty-search-removes-last-chip.

Installation

Initialize shadcn (once per project)Seeds lib/utils.ts and components.json. Skip if you've already used any shadcn component.
pnpm dlx shadcn@latest init
Install the component
pnpm dlx shadcn@latest add @ilinxa/entity-picker

Add -fixtures for dummy data:

pnpm dlx shadcn@latest add @ilinxa/entity-picker-fixtures

CLI can't resolve @ilinxa? The namespace is listed in the official shadcn registry directory, so current CLIs need no configuration. If yours can't resolve it (older or pinned versions, self-hosted mirrors), register it manually in components.json:

"registries": {
  "@ilinxa": "https://ui.ilinxa.com/r/{name}.json"
}

Preview

Search nodes…

Selected: —

Demo source

demo.tsxtsx
"use client"; import { useRef, useState } from "react";import { ChevronDown, Pin, UserCircle2 } from "lucide-react";import { Badge } from "@/components/ui/badge";import { Button } from "@/components/ui/button";import { Tabs, TabsContent, TabsTrigger } from "@/components/ui/tabs";import { SwipeTabsList } from "@/components/site/swipe-tabs-list";import { EntityPicker } from "./entity-picker";import {  GRAPH_NODES,  NODE_KINDS,  USERS,  type GraphNode,  type User,} from "./dummy-data";import type { EntityPickerHandle } from "./types"; function DemoFrame({ children }: { children: React.ReactNode }) {  return (    <div className="rounded-md border border-border bg-card p-5">      {children}    </div>  );} function SingleDemo() {  const [value, setValue] = useState<GraphNode | null>(null);  return (    <DemoFrame>      <div className="flex flex-col gap-3">        <label htmlFor="single-picker" className="text-xs text-muted-foreground">          Pick a graph node        </label>        <EntityPicker<GraphNode>          id="single-picker"          items={GRAPH_NODES}          value={value}          onChange={setValue}          kinds={NODE_KINDS}          triggerLabel="Search nodes…"        />        <p className="text-xs text-muted-foreground">          Selected: <span className="font-mono">{value?.label ?? "—"}</span>        </p>      </div>    </DemoFrame>  );} function MultiDemo() {  const [value, setValue] = useState<GraphNode[]>([    GRAPH_NODES[0],    GRAPH_NODES[7],  ]);  return (    <DemoFrame>      <div className="flex flex-col gap-3">        <label htmlFor="multi-picker" className="text-xs text-muted-foreground">          Pick multiple nodes        </label>        <EntityPicker<GraphNode>          id="multi-picker"          mode="multi"          items={GRAPH_NODES}          value={value}          onChange={setValue}          kinds={NODE_KINDS}          triggerLabel="Search nodes…"        />        <p className="text-xs text-muted-foreground">          Selected: <span className="font-mono">{value.length}</span> node{value.length === 1 ? "" : "s"}        </p>      </div>    </DemoFrame>  );} function NoKindsDemo() {  const [value, setValue] = useState<User | null>(null);  return (    <DemoFrame>      <div className="flex flex-col gap-3">        <label htmlFor="user-picker" className="text-xs text-muted-foreground">          Pick a teammate        </label>        <EntityPicker<User>          id="user-picker"          items={USERS}          value={value}          onChange={setValue}          triggerLabel="Search users…"        />        <p className="text-xs text-muted-foreground">          {value ? (            <>              <span className="font-mono">{value.label}</span> ·{" "}              <span className="font-mono">{value.email}</span>            </>          ) : (            "—"          )}        </p>      </div>    </DemoFrame>  );} function CustomMatchDemo() {  const [value, setValue] = useState<GraphNode[]>([]);  return (    <DemoFrame>      <div className="flex flex-col gap-3">        <p className="text-xs text-muted-foreground">          Custom match — substring across <code>label</code> AND{" "}          <code>description</code>.        </p>        <EntityPicker<GraphNode>          mode="multi"          items={GRAPH_NODES}          value={value}          onChange={setValue}          kinds={NODE_KINDS}          match={(item, query) => {            const q = query.toLowerCase();            return (              item.label.toLowerCase().includes(q) ||              (item.description?.toLowerCase().includes(q) ?? false)            );          }}          triggerLabel="Search labels & descriptions…"        />      </div>    </DemoFrame>  );} function CustomItemDemo() {  const [value, setValue] = useState<User[]>([]);  return (    <DemoFrame>      <div className="flex flex-col gap-3">        <p className="text-xs text-muted-foreground">          Custom <code>renderItem</code> — avatar + name + email.        </p>        <EntityPicker<User>          mode="multi"          items={USERS}          value={value}          onChange={setValue}          triggerLabel="Pick teammates…"          renderItem={(item, ctx) => (            <div className="flex flex-1 items-center gap-2">              <div className="grid size-7 place-items-center rounded-full bg-primary/10 font-mono text-[10px] font-semibold text-primary">                {item.avatar}              </div>              <div className="flex flex-1 flex-col">                <span className="text-sm">{item.label}</span>                <span className="font-mono text-[10px] text-muted-foreground">                  {item.email}                </span>              </div>              {ctx.selected ? (                <Badge variant="secondary" className="text-[10px]">                  selected                </Badge>              ) : null}            </div>          )}        />      </div>    </DemoFrame>  );} function CustomEmptyDemo() {  const [value, setValue] = useState<GraphNode | null>(null);  return (    <DemoFrame>      <div className="flex flex-col gap-3">        <p className="text-xs text-muted-foreground">          Custom <code>renderEmpty</code> — surfaces the query verbatim.        </p>        <EntityPicker<GraphNode>          items={GRAPH_NODES}          value={value}          onChange={setValue}          kinds={NODE_KINDS}          triggerLabel="Try typing something nonsense…"          renderEmpty={({ query, itemCount }) => (            <div className="flex flex-col items-center gap-1 px-3 py-2 text-center">              <p className="text-xs text-muted-foreground">                {itemCount === 0                  ? "No items provided."                  : `No matches for "${query}".`}              </p>              {query.length > 0 ? (                <p className="text-[10px] text-muted-foreground/70">                  Try a shorter prefix or check the spelling.                </p>              ) : null}            </div>          )}        />      </div>    </DemoFrame>  );} function CustomTriggerDemo() {  const [value, setValue] = useState<User | null>(null);  return (    <DemoFrame>      <div className="flex flex-col gap-3">        <p className="text-xs text-muted-foreground">          Custom <code>renderTrigger</code> — host owns the trigger chrome.        </p>        <EntityPicker<User>          items={USERS}          value={value}          onChange={setValue}          triggerLabel="Pick teammate…"          renderTrigger={({ value: v, open, triggerRef }) => (            <button              ref={(node) => triggerRef(node)}              type="button"              className="inline-flex items-center gap-2 rounded-md border border-input bg-card px-3 py-2 text-sm transition-colors hover:bg-muted/40"            >              <UserCircle2 aria-hidden="true" className="size-4" />              <span>                {v && !Array.isArray(v) ? v.label : "Pick teammate…"}              </span>              <ChevronDown                aria-hidden="true"                className={`size-3 transition-transform ${open ? "rotate-180" : ""}`}              />            </button>          )}        />      </div>    </DemoFrame>  );} function HandleDemo() {  const [value, setValue] = useState<GraphNode[]>([]);  const ref = useRef<EntityPickerHandle>(null);  return (    <DemoFrame>      <div className="flex flex-col gap-3">        <p className="text-xs text-muted-foreground">          Imperative handle — drive the picker from outside.        </p>        <EntityPicker<GraphNode>          ref={ref}          mode="multi"          items={GRAPH_NODES.filter((n) => n.kind === "person" || n.kind === "project")}          value={value}          onChange={setValue}          kinds={NODE_KINDS}          triggerLabel="People & projects…"        />        <div className="flex flex-wrap gap-2">          <Button            type="button"            size="sm"            variant="outline"            onClick={() => ref.current?.focus()}          >            focus()          </Button>          <Button            type="button"            size="sm"            variant="outline"            onClick={() => ref.current?.open()}          >            open()          </Button>          <Button            type="button"            size="sm"            variant="outline"            onClick={() => ref.current?.close()}          >            close()          </Button>          <Button            type="button"            size="sm"            variant="outline"            onClick={() => ref.current?.clear()}          >            clear()          </Button>        </div>        {value.length > 0 ? (          <div className="flex flex-wrap gap-1">            {value.map((v) => (              <Badge                key={v.id}                variant="secondary"                className="font-mono text-[10px]"              >                {v.kind === "person" ? <Pin className="size-2.5" /> : null}                {v.label}              </Badge>            ))}          </div>        ) : null}      </div>    </DemoFrame>  );} const PAGE_SIZE = 4; /** A fake server: filters GRAPH_NODES by `query`, one page at a time, with latency. */function fakeSearch(  query: string,  page: number,  fail: boolean,): Promise<{ items: GraphNode[]; hasMore: boolean }> {  return new Promise((resolve, reject) => {    setTimeout(() => {      if (fail) {        reject(new Error("The server did not answer."));        return;      }      const q = query.toLowerCase();      const all = GRAPH_NODES.filter((n) => n.label.toLowerCase().includes(q));      const end = (page + 1) * PAGE_SIZE;      resolve({ items: all.slice(0, end), hasMore: end < all.length });    }, 600);  });} function ServerSearchDemo() {  const [value, setValue] = useState<GraphNode[]>([]);  const [query, setQuery] = useState("");  const [items, setItems] = useState<GraphNode[]>([]);  const [hasMore, setHasMore] = useState(false);  const [page, setPage] = useState(0);  const [loading, setLoading] = useState(false);  const [loadingMore, setLoadingMore] = useState(false);  const [error, setError] = useState<string | undefined>(undefined);  const [failNext, setFailNext] = useState(false);  // Stale-response guard: only the latest request may write state.  const latest = useRef(0);   function load(q: string, nextPage: number, more: boolean) {    const id = ++latest.current;    setError(undefined);    if (more) setLoadingMore(true);    else setLoading(true);    fakeSearch(q, nextPage, failNext)      .then((res) => {        if (id !== latest.current) return;        setItems(res.items);        setHasMore(res.hasMore);        setPage(nextPage);        setFailNext(false);      })      .catch((e: Error) => {        if (id === latest.current) setError(e.message);      })      .finally(() => {        if (id !== latest.current) return;        setLoading(false);        setLoadingMore(false);      });  }   return (    <DemoFrame>      <div className="flex flex-col gap-3">        <p className="text-xs text-muted-foreground">          The host owns the data: controlled <code>query</code>,{" "}          <code>{`filterItems={false}`}</code>, <code>loading</code> /{" "}          <code>error</code> + <code>onRetry</code>, and a <code>hasMore</code>{" "}          / <code>onLoadMore</code> pair. The fake server answers after 600 ms.        </p>        <EntityPicker<GraphNode>          mode="multi"          items={items}          value={value}          onChange={setValue}          kinds={NODE_KINDS}          query={query}          onQueryChange={(q, reason) => {            setQuery(q);            if (reason === "input") load(q, 0, false);          }}          onOpenChange={(open) => {            if (open) load(query, 0, false);          }}          filterItems={false}          loading={loading}          error={error}          onRetry={() => load(query, 0, false)}          hasMore={hasMore}          onLoadMore={() => load(query, page + 1, true)}          loadingMore={loadingMore}          labels={{ searchPlaceholder: "Search the server…" }}        />        <div className="flex flex-wrap items-center gap-2">          <Button            type="button"            size="sm"            variant={failNext ? "default" : "outline"}            aria-pressed={failNext}            onClick={() => setFailNext((f) => !f)}          >            Fail the next request          </Button>          <span className="text-xs text-muted-foreground">            Selected: <span className="font-mono">{value.length}</span>          </span>        </div>      </div>    </DemoFrame>  );} const AR_NODES: GraphNode[] = [  { id: "ar-1", label: "القاهرة", kind: "org" },  { id: "ar-2", label: "الرياض", kind: "org" },  { id: "ar-3", label: "عمّان", kind: "org" },]; const AR_LABELS = {  searchPlaceholder: "ابحث…",  searchLabel: "ابحث عن كيان",  triggerPlaceholder: "اختر…",  removeChip: (label: string) => `إزالة ${label}`,  nothingToPick: "لا يوجد ما يمكن اختياره",  noResults: "لا توجد نتائج",}; function RtlDemo() {  const [value, setValue] = useState<GraphNode[]>([AR_NODES[0]]);  return (    <DemoFrame>      <div dir="rtl" lang="ar" className="flex flex-col gap-3">        <p className="text-xs text-muted-foreground">          Right-to-left host: logical spacing, localized <code>labels</code>,          and <code>{`locale="ar"`}</code> for case folding.        </p>        <EntityPicker<GraphNode>          mode="multi"          items={AR_NODES}          value={value}          onChange={setValue}          kinds={NODE_KINDS}          labels={AR_LABELS}          locale="ar"        />      </div>    </DemoFrame>  );} export default function EntityPickerDemo() {  return (    <Tabs defaultValue="single">      <SwipeTabsList>        <TabsTrigger value="single">Single</TabsTrigger>        <TabsTrigger value="multi">Multi</TabsTrigger>        <TabsTrigger value="no-kinds">No kinds</TabsTrigger>        <TabsTrigger value="custom-match">Custom match</TabsTrigger>        <TabsTrigger value="custom-item">Custom item</TabsTrigger>        <TabsTrigger value="custom-empty">Custom empty</TabsTrigger>        <TabsTrigger value="custom-trigger">Custom trigger</TabsTrigger>        <TabsTrigger value="handle">Imperative handle</TabsTrigger>        <TabsTrigger value="server">Server search</TabsTrigger>        <TabsTrigger value="rtl">RTL</TabsTrigger>      </SwipeTabsList>      <TabsContent value="single" className="mt-4">        <SingleDemo />      </TabsContent>      <TabsContent value="multi" className="mt-4">        <MultiDemo />      </TabsContent>      <TabsContent value="no-kinds" className="mt-4">        <NoKindsDemo />      </TabsContent>      <TabsContent value="custom-match" className="mt-4">        <CustomMatchDemo />      </TabsContent>      <TabsContent value="custom-item" className="mt-4">        <CustomItemDemo />      </TabsContent>      <TabsContent value="custom-empty" className="mt-4">        <CustomEmptyDemo />      </TabsContent>      <TabsContent value="custom-trigger" className="mt-4">        <CustomTriggerDemo />      </TabsContent>      <TabsContent value="handle" className="mt-4">        <HandleDemo />      </TabsContent>      <TabsContent value="server" className="mt-4">        <ServerSearchDemo />      </TabsContent>      <TabsContent value="rtl" className="mt-4">        <RtlDemo />      </TabsContent>    </Tabs>  );} 

Usage

When to use

Reach for EntityPicker whenever a host has a list of typed entities (graph nodes, users, files, organizations, …) and a user needs to pick one or many. Generic over the entity type via <EntityPicker<T extends EntityLike>>; supports single or multi mode with mode-aware value typing via TypeScript function overloads. Built on shadcn Command (cmdk) for search and Popover for the dropdown.

Basic single

import { EntityPicker } from "@/components/entity-picker";

interface Node {
  id: string;
  label: string;
  kind: "person" | "project";
}

const NODES: Node[] = [/* ... */];

export function NodePicker() {
  const [value, setValue] = useState<Node | null>(null);
  return (
    <EntityPicker<Node>
      items={NODES}
      value={value}
      onChange={setValue}
      triggerLabel="Pick a node"
    />
  );
}

Multi

Set mode="multi". value becomes T[]; chips render in the trigger; Backspace on empty search removes the last chip; chip-X buttons remove individual chips. Selection order is the order picked (no drag-to-reorder).

<EntityPicker<Node>
  mode="multi"
  items={NODES}
  value={selected}
  onChange={setSelected}
/>

Kinds + badges

When items carry a kind, supply a kinds: Record<string, KindMeta> map keyed by kind value. Each KindMeta has a label and an optional color (CSS variable name or OKLCH literal). Badges render in result rows + chips; toggle with showKindBadges (defaults to true iff any item or any selected value has a kind, so chips keep their badge while items is empty).

Custom match

Default match is case-insensitive substring on item.label via String.toLowerCase(), or toLocaleLowerCase(locale) when you pass locale (so locale="tr"finds "İstanbul" for "istanbul"). Pass match: (item, query) => boolean for richer search (e.g., search across description, fuzzy-rank via Fuse.js, or Intl.Collator for accent-insensitive matching). Filter cost runs on every keystroke; keep predicates cheap.

Custom slots

  • renderItem(item, ctx) — replace the result row body. ctx has { selected, query }. The CommandItem chrome (highlight, click handler) is preserved.
  • renderTrigger(ctx) — replace the trigger entirely. ctx has { value, open, triggerRef }. Attach triggerRef to your root focusable element so focus() ref method works.
  • renderEmpty(ctx) — replace the empty-state copy. ctx has { query, itemCount }; default is "No results" or "Nothing to pick from".

properties-form integration

When composing entity-picker inside properties-form's custom field renderer, pass id={fieldId} from FieldRendererProps so <label htmlFor={fieldId}> associates correctly.

{
  key: "owner",
  type: "string",  // type ignored when renderer is set
  label: "Owner",
  renderer: ({ value, onChange, fieldId, error, errorId }) => (
    <EntityPicker<User>
      id={fieldId}
      items={users}
      value={value as User | null}
      onChange={onChange}
      triggerLabel="Pick owner"
    />
  ),
}

Imperative handle

const ref = useRef<EntityPickerHandle>(null);
// ...
ref.current?.focus();
ref.current?.open();
ref.current?.close();
ref.current?.clear();

Items reference stability

Inline items={[...]}rebuilds entity references each render and re-derives cmdk's filter index. In-repo, the React Compiler memoizes inline literals at the call site. For NPM consumers without the Compiler, hoist to module scope or wrap with useMemo. A dev-only warning fires after >5 successive unstable renders.

Selection equality

onChange fires only when the id-set of the selection changes. Same-id new-reference values do not fire (avoids spurious re-renders when the host re-derives entity objects upstream).

Keyboard

  • Tab / Shift+Tab — focus trigger and chip-X buttons.
  • Enter / Space / ↓ on trigger — open dropdown.
  • ↑ / ↓ inside search — navigate results (cmdk).
  • Enter on highlighted result — toggle selection.
  • Esc — close dropdown.
  • Backspace on empty search (multi mode) — remove last chip.

Server-side search (the host owns the data)

The picker never fetches. You own the query, the request and the items; the picker shows what you give it. Control the search text with query / onQueryChange, turn the built-in filter off with filterItems={false}(rows render as given, match is ignored), and report the request state with loading, error and onRetry. Precedence is loading, then error, then empty; the Retry button renders only when onRetryis passed. Pagination is a "Load more" row that appears only when both hasMore and onLoadMore are passed (loadingMore disables it while a page loads). Guard against stale responses in your fetch layer, and pass only the latest result.

const [query, setQuery] = useState("");
const { data, isFetching, isError, refetch, hasNextPage, fetchNextPage, isFetchingNextPage } =
  useMyInfiniteSearch(query);

<EntityPicker<User>
  items={data ?? []}
  value={value}
  onChange={setValue}
  query={query}
  onQueryChange={(q) => setQuery(q)}   // reason: "input" | "reset" (on close)
  filterItems={false}
  loading={isFetching && !isFetchingNextPage}
  error={isError}
  onRetry={refetch}
  hasMore={hasNextPage}
  onLoadMore={fetchNextPage}
  loadingMore={isFetchingNextPage}
/>

When loading settles while the popover is open, a polite live region announces labels.resultsCount(count, formatted) once (not per keystroke). Use renderLoading / renderError to replace the default rows.

Labels and locale

Every string is a key of labels (a partial of EntityPickerLabels; an undefined key keeps the default). The English defaults are exported as defaultEntityPickerLabels. placeholder and triggerLabel still work as deprecated aliases and win over their keys. localedrives the default match's case folding and the number passed to resultsCount.

<EntityPicker<City>
  items={cities}
  value={city}
  onChange={setCity}
  locale="tr"
  labels={{
    searchPlaceholder: "Ara…",
    searchLabel: "Şehir ara",
    triggerPlaceholder: "Şehir seç…",
    removeChip: (label) => label + " öğesini kaldır",
    noResults: "Sonuç yok",
    nothingToPick: "Seçenek yok",
    resultsCount: (n, formatted) => formatted + " sonuç",
  }}
/>

Not implemented

  • Virtualization for very long lists.
  • "Create new" affordance via onCreate(query).
  • Multi-section grouping via groups.
  • Drag-to-reorder chips (multi mode).
  • Fuzzy-rank via rank: (item, query) => number.
  • Infinite scroll (pagination is the "Load more" row).

Features

  • Single OR multi mode via `mode` prop with mode-aware value typing (function overloads)
  • Searchable via shadcn Command (cmdk) with case-insensitive substring default
  • Custom match function for richer search (e.g., search across description)
  • Kind badges via `kinds: Record<string, KindMeta>` map; OKLCH color literals supported
  • Custom render slots — renderItem / renderTrigger / renderEmpty
  • Multi-mode chip cluster with per-chip remove buttons and Backspace-on-empty-search removal
  • Controlled-or-uncontrolled open state mirroring Radix Popover convention
  • id-set selection equality — onChange fires only when selection ids change
  • Field trigger is a real full-field `<button>` overlay beneath a click-transparent chip layer (F-cross-13: no asChild) — chips keep their own nested remove buttons legally
  • Host-owned async data: controlled `query` + `onQueryChange(query, 'input' | 'reset')`, `filterItems={false}` to render server results as given (`match` ignored)
  • Async states — `loading` / `error` (true or message) / `onRetry` (Retry renders only with it), `renderLoading` / `renderError`; precedence loading > error > empty; `aria-busy` on the list and a polite results-count announcement once loading settles
  • Pagination — a 'Load more' row when both `hasMore` and `onLoadMore` are given; `loadingMore` disables it
  • Typed `labels` (`EntityPickerLabels`, exported `defaultEntityPickerLabels`); `placeholder` / `triggerLabel` remain as deprecated aliases that win over their keys
  • `locale` — default match folds case with `toLocaleLowerCase(locale)` (Turkish İ/ı); also formats the results count
  • Kind badges derive from `items` and the selection, so chips keep their badge while `items` is empty
  • Imperative handle — focus / open / close / clear
  • WAI-ARIA 1.2 combobox pattern; cmdk + Radix Popover handle most of the wiring

Tags

entity-pickerpickercomboboxgraph-system

Dependencies

shadcn primitives: badge, command, popover
npm peer deps: lucide-react@^1.11.0