ProjectMultiPicker

Searches projects on the server, showing each one’s thumbnail and status, and binds the ones you tick.

Single and multi: ProjectPicker takes one project.

Install

ReactSvelte

pnpm dlx shadcn@latest add https://sg-widgets.vercel.app/r/react/project-multi-picker.json

pnpm dlx shadcn-svelte@latest add https://sg-widgets.vercel.app/r/svelte/project-multi-picker.json

ProjectMultiPicker: chips, archived projects, hydration, summary modes, sizes, states

ReactSvelte

Reduce motionRadius: themeRadius: noneRadius: smRadius: mdRadius: lgRadius: xl

React

Loading the React demo…

Svelte

Loading the Svelte demo…

Props

prop	type	default	meaning
includeArchived	boolean	false	Offer projects whose archived checkbox is set.
summaryfrom EntityMultiPicker	'chips' | 'ellipsis' | 'count'	'ellipsis'	What the control shows for the selection.
maxfrom EntityMultiPicker	number	0	Chips drawn before the rest becomes +n. 0 lets the row fit what it can.
contextfrom EntityPicker	SgContext	required	The widget context. Every read goes through it, so widgets on a page share one cache.
value	EntityRef[]	[]	The chosen projects, in the order they were ticked. Two-way in Svelte.
labelFieldfrom EntityPicker	string	display-name chain	Field holding the row label.
searchFieldsfrom EntityPicker	SearchFieldSpec[] | ((query) => SearchFieldSpec[])	—	Fields matched on top of the display-name chain. A function is called with the query.
secondaryFieldfrom EntityPicker	string | CollectionColumn | null	null	Field shown right-aligned, drawn by its data type. A resolved column renders it by type.
secondaryfrom EntityPicker	(row) => string	—	Right-aligned text of your own. Wins over secondaryField.
subLabelFieldfrom EntityPicker	string | CollectionColumn | null	null	Field shown under the label, drawn by its data type: a status reads its display name.
subLabelfrom EntityPicker	(row) => string	the type, when several are searched	Computes the sub-label.
thumbnailfrom EntityPicker	string | false	'image'	Field holding the thumbnail URL. false hides the leading slot.
roundThumbnailfrom EntityPicker	boolean	false	Draws the thumbnail as a circle.
showCodefrom EntityPicker	boolean	false	Shows the row's code beside the label when the two differ.
siteUrlfrom EntityPicker	string	the context's	The site the status sprite is served from, for a secondary that is a status.
fieldsfrom EntityPicker	string[]	—	Extra fields to request.
filtersfrom EntityPicker	FilterGroup | WireGroup | null	null	Pre-filter, merged into every search with and.
projectIdfrom EntityPicker	number	—	Scopes to one project.
excludefrom EntityMultiPicker	EntityRef[]	—	Rows kept out of the results, per type.
minQueryLengthfrom EntityPicker	number	0	Under it the query carries no name condition.
pageSizefrom EntityPicker	number	20	Rows a page, with a load more row under them.
debounceMsfrom EntityPicker	number	250	Wait after the last keystroke before searching.
class / classNamefrom EntityPicker	string	—	Merged after the widget's own classes.
sizefrom PickerControl	'sm' | 'md' | 'lg'	'md'	Control height: 7, 8 and 9.
disabledfrom PickerControl	boolean	false
readonlyfrom EntityPicker	boolean	false	Keeps full contrast and drops the affordances.
invalidfrom EntityPicker	boolean	false	Sets aria-invalid and the destructive ring.
clearablefrom EntityMultiPicker	boolean	true	Shows the clear-all control.
placeholder	string	'Search for projects'	Shown in the control while nothing is chosen.
searchPlaceholderfrom EntityPicker	string	'Search…'	Shown in the query input once something is chosen.
openfrom PickerControl	boolean	required	React: whether the popup is showing.
openfrom PickerControl	boolean	false	Svelte: whether the popup is showing, two-way.
emptyLabelfrom EntityPicker	string	'No match'	Shown when a query matches nothing.
loadingLabelfrom EntityPicker	string	'Loading…'	Names the skeletons a read stands behind, for a screen reader.
errorLabelfrom EntityPicker	string	—	Shown in place of what the failed read said.

placeholder defaults to Search for projects. summary and max set what the control shows for the selection, as on every other multi picker.

The sub-label is the project’s status, so an active project can be told from a bidding one.

Every row carries a checkbox and the list stays open across selections. Selected rows are appended to the option list after the search results, so a project stays there to be unticked whatever the query. Each selection is also a chip in the control, with its own remove control.

Events

event	payload	when
onValueChangefrom EntityMultiPicker	EntityRef[], PickerRow[]	The selection changed.
onErrorfrom EntityPicker	Error	A read failed. The list shows it inline as well.
onOpenChangefrom EntityPicker	boolean	The popup opened or closed. Svelte also binds it with bind:open.

Slots

None.

Keyboard

key	does
any textfrom EntityMultiPicker	Searches the server, from the caret under chips and from the popup's search box otherwise.
Enter, Spacefrom EntityPicker	On the chevron, opens the list.
Up, Downfrom EntityPicker	Moves the highlight through the rows and keeps it in view, including across a load more page. The last row holds it rather than wrapping.
ArrowDown / ArrowUpfrom PickerControl	Moves the highlight, and the list scrolls it into view.
Enterfrom EntityMultiPicker	Ticks or unticks the highlighted row. The list stays open.
Escapefrom EntityPicker	Closes the list and clears the query. On a closed picker it does nothing.
Backspacefrom EntityMultiPicker	In an empty search box, highlights the last chip. A second one removes it. Any other key releases it.
ArrowLeft / ArrowRightfrom PickerControl	On a chip, walks the row. ArrowRight past the last chip returns to the input.
Deletefrom PickerControl	On a chip, removes it and leaves the caret on its neighbour.
Tabfrom EntityMultiPicker	Moves through the chips' remove controls, then +n, the clear control and the chevron.

API behaviour

Project’s status field is sg_status, a plain list with no Status row behind it, where every other type uses sg_status_list (entity_types/Project).

sg_status is not a liveness filter and is null on most projects; archived, is_template and is_demo are the discriminators, which is why hiding archived projects filters on archived (018_project_listing).

Project is site-wide and has no project field, so projectId adds nothing on this picker.

Reference

The row, chip and checkbox anatomy follows shadcn’s Base UI Combobox, read through shadcn 4.21.0. The primitive underneath is Base UI Combobox 1.8.0 in React and Bits UI Combobox 2.19.1 in Svelte. shadcn-svelte ships no combobox item, so each widget composes the headless primitive of its framework and both draw the same rows, the same classes and the same states.