KQ-1168 · CATALOG/SELECT

Catalog Select

A select whose options are index cards in a catalog drawer: opening pulls the drawer out on springs.glide (or by hand, 1:1, committing by projection), the card being read stands tipped toward you, and moving on makes it fall forward over its bottom edge while the file glides a place nearer — moving back flips the last fallen card up on springs.snap, and jumps riffle card by card on cascade(). Choosing lifts the card up into the field on springs.glide as the drawer shuts under it. It is the select-only combobox pattern: focus stays on the field, arrows, Page keys, Home and End move, typing jumps by first letters, Enter chooses and Escape shuts.

KQ-1168 · CATALOG/SELECT

Subject

Shelf marks print on your pass.

drawer open · arrows flip, enter chooses

Open it on the Atelier stage

Install

One command — the source lands in your repo. Or copy it from the Code tab.

$ pnpm dlx shadcn@latest add @kinetiq/catalog-select

Props

label: string; default —; What is being chosen. The visible label and the listbox's name.
options: CatalogOption[]; default —; The cards: { value, label, detail?, disabled? }. The label is the card's heading and tab and what typing jumps by.
value / defaultValue: string | null; default null; The chosen option's value, controlled or initial.
onValueChange: (value: string) => void; default —; Fires from the key, click or tap that chose a card.
open / defaultOpen: boolean; default false; Whether the drawer is pulled out, controlled or initial.
onOpenChange: (open: boolean) => void; default —; Fires from the key, pull or press that opened or shut the drawer.
placeholder: string; default "Choose one"; Shown in the field before anything is chosen.
drawerLabel: string; default —; The label in the holder on the drawer's front. Defaults to the first and last initials, "A – Z".
cards: number; default 7; How many cards stand in view in the open drawer, 4 to 12: wide tabs at 4, a packed file at 12.
drawer: "oak" | "steel" | "card"; default "oak"; The drawer's material: grained oak with brass, brushed steel, or kraft board.
flip: number; default 0.7; How far the card being read tips toward you, 0 to 1; the paper is louder with it.
name: string; default —; Form field name; a hidden input carries the chosen value.
hint: string; default —; Helper text under the drawer.
error: string; default —; An error from the host; replaces the hint and marks the field invalid.
required: boolean; default false; Shutting the drawer with nothing chosen shows "Choose one to continue."
disabled: boolean; default false; Turns the field and the drawer off.
sound: boolean; default false; Play the paper of each flip and the drawer's thock. Heard only just after the visitor's own input.
className: string; default —; Classes for the root.

Prop	Type	Default	Description
label	string	—	What is being chosen. The visible label and the listbox's name.
options	CatalogOption[]	—	The cards: { value, label, detail?, disabled? }. The label is the card's heading and tab and what typing jumps by.
value / defaultValue	string \| null	null	The chosen option's value, controlled or initial.
onValueChange	(value: string) => void	—	Fires from the key, click or tap that chose a card.
open / defaultOpen	boolean	false	Whether the drawer is pulled out, controlled or initial.
onOpenChange	(open: boolean) => void	—	Fires from the key, pull or press that opened or shut the drawer.
placeholder	string	"Choose one"	Shown in the field before anything is chosen.
drawerLabel	string	—	The label in the holder on the drawer's front. Defaults to the first and last initials, "A – Z".
cards	number	7	How many cards stand in view in the open drawer, 4 to 12: wide tabs at 4, a packed file at 12.
drawer	"oak" \| "steel" \| "card"	"oak"	The drawer's material: grained oak with brass, brushed steel, or kraft board.
flip	number	0.7	How far the card being read tips toward you, 0 to 1; the paper is louder with it.
name	string	—	Form field name; a hidden input carries the chosen value.
hint	string	—	Helper text under the drawer.
error	string	—	An error from the host; replaces the hint and marks the field invalid.
required	boolean	false	Shutting the drawer with nothing chosen shows "Choose one to continue."
disabled	boolean	false	Turns the field and the drawer off.
sound	boolean	false	Play the paper of each flip and the drawer's thock. Heard only just after the visitor's own input.
className	string	—	Classes for the root.