ComponentPicker

When to use

Use it when your product needs a component catalog browser: search components, filter by category, read the props table and examples, then hand the chosen slug back. Typical hosts are the component panel of an AI site builder, an internal design-system portal, and the block palette of a low-code editor.

• For a plain quick-jump palette without a category tree or props table, use Command directly, or the ComponentPickerCommand wrapper exported here.
• To pick an icon use IconPicker; to pick an emoji use EmojiPicker.
• For a general list page with a query bar rather than a component catalog, use ProTable.

Three boundaries are deliberate, not unfinished work:

1. It never fetches. items comes from the consumer. A library component must not assume the runtime has llms-full.txt, and must not issue a network request while rendering. Call the pure parseComponentCatalog(text) in your own layer instead.
2. It never renders an arbitrary component. There is no slug-to-component registry inside the library, and no string evaluation or iframe. Inject a live preview through renderPreview; without it the preview area shows a placeholder.
3. It does not pull in fuse.js. The ranker is a pure function in this folder, tuned so that a hit on slug or name outweighs a hit on description. A generic library cannot make that distinction: searching btn would float any component whose description happens to scatter b, t, and n above Button.

Import

Props

ComponentPickerProps

ComponentPickerItem: { slug, name, description, category, group, tags?, props?, examples? }.
ComponentPickerProp: { name, type?, default?, description?, required? }.
ComponentPickerExample: { title?, lang?, code }.

ComponentPickerCommandProps: items / open / onOpenChange / onSelect / placeholder / emptyMessage / maxResults (default 30) / groupByCategory (default true) / shortcut.

Events

Slots

Pure functions

Example

Accessibility

• The search box is a role="combobox" with aria-controls, aria-autocomplete="list", and aria-activedescendant. The result grid is a role="listbox" and every card is a role="option" with aria-selected. Focus stays in the search box and aria-activedescendant points at the highlighted card, which is the WAI-ARIA combobox pattern; focus is never moved between cards.
• Keyboard: Down and Up move the highlight and wrap around, starting at the first card going down and the last card going up. Enter confirms. Escape backs out one level at a time, clearing the query first and the highlight second. The highlighted card is scrolled with scrollIntoView({ block: "nearest" }).
• The category tree runs Tree in expandTrigger="icon" mode, so only the arrow expands a branch and the rest of the row still selects. That is what makes a whole category such as forms selectable.
• The detail pane is a role="region" with an accessible name, so a screen reader can jump straight into it.

Usage notes

• A height is mandatory. Without one in className the whole block collapses to content height and every independent scroll area stops working, same as Flow and AdminLayout.
• A controlled `filter` needs `onFilterChange`. Use defaultFilter when you only want an initial value. Passing filter without the callback leaves the search box unwritable and the tree unclickable, which reads as a broken component.
• `renderPreview` is the only preview path, not an optional convenience. The library will not turn a slug into an instance for you. Leave showPreview at false if you do not want to supply it.
• The second argument of `onSelect` may be `{}`. defaultPropsOf only accepts literal defaults such as true, false, numbers, and quoted strings. Documented defaults written as () => void, {...}, or an em dash are skipped on purpose; the empty object is honest, not a parse failure.
• `parseComponentCatalog` does not read the slug from the document, because it is not there. The function first harvests cross-reference links across the whole text, so [Formula](.../components/math) yields math, and only then falls back to kebab-casing the component name. Those two steps cover all 376 entries of this library; the single exception, QRCode to qrcode, is covered by a built-in override. Pass slugOverrides for the abbreviations in your own docs.
• `maxResults` caps rendering, not scoring. Every item is scored before the list is truncated, so entry 61 really is ranked 61st rather than dropped. Raise it to see everything, but 376 cards at once will visibly drop frames.
• UI copy follows the locale by default. Without labels, every string comes from the ConfigProvider locale and falls back to the built-in Chinese when no provider is present; placeholder and emptyMessage on ComponentPickerCommand work the same way. Priority is prop, then locale, then fallback, so overriding one key leaves the rest tracking the app language.
• `ComponentPickerCommand` is not the main form. A command line has no room for a category tree or a props table. Internally it uses filter={() => true} with onQueryChange to take over ordering, because the palette's own filter is a substring match that does not rank.