{"name":"listbox","title":"Listbox","description":"An always-visible list of options with single or multiple selection and keyboard navigation.","installCommand":"bunx marko-ui add listbox -y","usageTags":"<Listbox>","importSnippet":"import Listbox from \"@/components/ui/listbox/listbox.marko\";","usageSnippet":"static const fruits = [\n  { value: \"apple\", label: \"Apple\" },\n  { value: \"banana\", label: \"Banana\" },\n];\n\n<Listbox items=fruits label=\"Favorite fruit\" defaultValue=[\"apple\"]/>","tags":["Listbox"],"parts":[{"name":"option","attributes":[{"name":"value","type":"string","required":true},{"name":"label","type":"string","required":true},{"name":"disabled","type":"boolean","required":false}],"repeatable":true}],"props":[{"name":"defaultHighlightedValue","type":"string | null | undefined","required":false,"description":"The initial value of the highlighted item when opened.\nUse when you don't need to control the highlighted value of the listbox."},{"name":"defaultValue","type":"string[] | undefined","required":false,"default":"[]","description":"The initial default value of the listbox when rendered.\nUse when you don't need to control the value of the listbox."},{"name":"deselectable","type":"boolean | undefined","required":false,"description":"Whether to disallow empty selection"},{"name":"dir","type":"'ltr' | 'rtl' | undefined","required":false,"default":"ltr","description":"The document's text/writing direction."},{"name":"disabled","type":"boolean | undefined","required":false,"description":"Whether the listbox is disabled"},{"name":"disallowSelectAll","type":"boolean | undefined","required":false,"description":"Whether to disallow selecting all items when `meta+a` is pressed"},{"name":"getRootNode","type":"(() => ShadowRoot | Document | Node) | undefined","required":false,"description":"A root node to correctly resolve document in custom environments. E.x.: Iframes, Electron."},{"name":"highlightedValue","type":"string | null | undefined","required":false,"description":"The controlled key of the highlighted item"},{"name":"ids","type":"ElementIds | undefined","required":false,"description":"The ids of the elements in the listbox. Useful for composition."},{"name":"items","type":"ListboxItem[]","required":false},{"name":"label","type":"string","required":false},{"name":"loopFocus","type":"boolean | undefined","required":false,"default":"false","description":"Whether to loop the keyboard navigation through the options"},{"name":"orientation","type":"'horizontal' | 'vertical' | undefined","required":false,"default":"vertical","description":"The orientation of the listbox."},{"name":"scrollToIndexFn","type":"((details: ScrollToIndexDetails) => void) | undefined","required":false,"description":"Function to scroll to a specific index"},{"name":"selectionMode","type":"SelectionMode | undefined","required":false,"default":"single","description":"How multiple selection should behave in the listbox.\n\n- `single`: The user can select a single item.\n- `multiple`: The user can select multiple items without using modifier keys.\n- `extended`: The user can select multiple items by using modifier keys."},{"name":"selectOnHighlight","type":"boolean | undefined","required":false,"description":"Whether to select the item when it is highlighted"},{"name":"typeahead","type":"boolean | undefined","required":false,"description":"Whether to enable typeahead on the listbox"},{"name":"value","type":"string[] | undefined","required":false,"description":"The controlled keys of the selected items"}],"events":[{"name":"highlightedValueChange","arg":"string"},{"name":"onHighlightChange","arg":"HighlightChangeDetails<T>","description":"The callback fired when the highlighted item changes."},{"name":"onSelect","arg":"SelectionDetails","description":"Function called when an item is selected"},{"name":"onValueChange","arg":"ValueChangeDetails<T>","description":"The callback fired when the selected item changes."},{"name":"valueChange","arg":"string[]"}],"keyboard":[],"accessibilityNotes":[],"examples":[{"id":"listbox-demo","title":"Basic","source":"import Listbox from \"@marko-ui/shadcn/ui/listbox/listbox.marko\";\n\nstatic const fruits = [\n  { value: \"apple\", label: \"Apple\" },\n  { value: \"banana\", label: \"Banana\" },\n  { value: \"blueberry\", label: \"Blueberry\" },\n  { value: \"grapes\", label: \"Grapes\" },\n  { value: \"pineapple\", label: \"Pineapple\" },\n];\n\n<Listbox items=fruits label=\"Favorite fruit\" defaultValue=[\"apple\"]/>","description":"A single-selection listbox with a label."},{"id":"listbox-multiple","title":"Multiple selection","source":"import Listbox from \"@marko-ui/shadcn/ui/listbox/listbox.marko\";\n\nstatic const fruits = [\n  { value: \"apple\", label: \"Apple\" },\n  { value: \"banana\", label: \"Banana\" },\n  { value: \"blueberry\", label: \"Blueberry\" },\n  { value: \"grapes\", label: \"Grapes\" },\n  { value: \"pineapple\", label: \"Pineapple\" },\n];\n\n<Listbox items=fruits label=\"Fruits\" selectionMode=\"multiple\" defaultValue=[\"apple\", \"grapes\"]/>","description":"Pass `selectionMode=\"multiple\"` to let the user select more than one item without modifier keys."},{"id":"listbox-disabled","title":"Disabled items","source":"import Listbox from \"@marko-ui/shadcn/ui/listbox/listbox.marko\";\n\nstatic const fruitsWithDisabled = [\n  { value: \"apple\", label: \"Apple\" },\n  { value: \"banana\", label: \"Banana\", disabled: true },\n  { value: \"blueberry\", label: \"Blueberry\" },\n  { value: \"grapes\", label: \"Grapes\", disabled: true },\n  { value: \"pineapple\", label: \"Pineapple\" },\n];\n\n<Listbox items=fruitsWithDisabled label=\"Favorite fruit\" defaultValue=[\"apple\"]/>","description":"Mark individual items with `disabled: true` to skip them in keyboard navigation and pointer input."},{"id":"listbox-controlled","title":"Controlled","source":"import Listbox from \"@marko-ui/shadcn/ui/listbox/listbox.marko\";\n\nstatic const fruits = [\n  { value: \"apple\", label: \"Apple\" },\n  { value: \"banana\", label: \"Banana\" },\n  { value: \"blueberry\", label: \"Blueberry\" },\n  { value: \"grapes\", label: \"Grapes\" },\n  { value: \"pineapple\", label: \"Pineapple\" },\n];\n\n<let/value=[\"banana\"]/>\n\n<div class=\"flex flex-col gap-2\">\n  <Listbox items=fruits label=\"Favorite fruit\" value:=value/>\n  <p class=\"text-sm text-muted-foreground\">Selected: ${value.join(\", \") || \"none\"}</p>\n</div>","description":"Zag machines are controlled: a `value` prop without a change handler never moves. Pair it with `valueChange`, or use Marko's bind shorthand `value:=state`.","essential":true},{"id":"listbox-compound","title":"Compound (attr tags)","source":"import Listbox from \"@marko-ui/shadcn/ui/listbox/listbox.marko\";\n\n<Listbox class=\"w-[240px]\" label=\"Favorite fruit\" defaultValue=[\"apple\"]>\n  <@option value=\"apple\" label=\"Apple\"/>\n  <@option value=\"banana\" label=\"Banana\"/>\n  <@option value=\"blueberry\" label=\"Blueberry\"/>\n  <@option value=\"grapes\" label=\"Grapes\"/>\n  <@option value=\"pineapple\" label=\"Pineapple\"/>\n</Listbox>","description":"Use `<@option>` attribute tags instead of `items=` to compose each option directly in markup.","essential":true}],"importInstallCommand":"bun add @marko-ui/shadcn marko-zag","nativeAttributes":"div","itemTypes":[{"prop":"items","typeName":"ListboxItem","fields":[{"name":"value","type":"string","required":true},{"name":"label","type":"string","required":true},{"name":"disabled","type":"boolean","required":false}]}]}