{"record":{"id":"1dbc0f40eca06e50","repo":"tailwindlabs/headlessui","slug":"missing-options-in-virtual-mode","errorCode":null,"errorMessage":"Missing `options` in virtual mode","messagePattern":"Missing `options` in virtual mode","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/@headlessui-react/src/components/combobox/combobox.tsx","lineNumber":1355,"sourceCode":"  //\n  // When the `static` prop is used, we should never freeze, because rendering\n  // is up to the user.\n  let shouldFreeze = visible && comboboxState === ComboboxState.Closed && !props.static\n\n  let options = useFrozenData(shouldFreeze, data.virtual?.options)\n\n  // Frozen state, the selected value will only update visually when the user re-opens the <Combobox />\n  let frozenValue = useFrozenData(shouldFreeze, data.value)\n\n  let isSelected = useCallback(\n    (compareValue: unknown) => data.compare(frozenValue, compareValue),\n    [data.compare, frozenValue]\n  )\n\n  // Map the children in a scrollable container when virtualization is enabled\n  let newDataContextValue = useMemo(() => {\n    if (!data.virtual) return data\n    if (options === undefined) throw new Error('Missing `options` in virtual mode')\n\n    return options !== data.virtual.options\n      ? { ...data, virtual: { ...data.virtual, options } }\n      : data\n  }, [data, options, data.virtual?.options])\n\n  if (data.virtual) {\n    Object.assign(theirProps, {\n      children: (\n        <ComboboxDataContext.Provider value={newDataContextValue}>\n          {/* @ts-expect-error The `children` prop now is a callback function that receives `{option}` */}\n          <VirtualProvider slot={slot}>{theirProps.children}</VirtualProvider>\n        </ComboboxDataContext.Provider>\n      ),\n    })\n  }\n\n  let render = useRender()","sourceCodeStart":1337,"sourceCodeEnd":1373,"githubUrl":"https://github.com/tailwindlabs/headlessui/blob/eea57cf46fd6767ed1059012f7073b88eb159fba/packages/@headlessui-react/src/components/combobox/combobox.tsx#L1337-L1373","documentation":"In Headless UI React's Combobox, virtual mode is enabled by passing `virtual={...}` (a virtualizer config). A useMemo then requires the top-level `options` prop to be present so it can feed the option list to the virtualizer; if `options === undefined` while `data.virtual` is set, it throws 'Missing `options` in virtual mode'.","triggerScenarios":"`<Combobox virtual={virtualizer}>` without an `options` prop; passing options only via `<ComboboxOption>` children (which don't work in virtual mode); destructuring options conditionally so it becomes undefined on some renders.","commonSituations":"Migrating a Combobox to @tanstack/react-virtual-based virtual mode and forgetting the required `options` array; supplying options to the virtualizer object but not as the `options` prop; lazy-loading options where the first render passes undefined.","solutions":["Pass the flat options array as a prop: `<Combobox virtual={virtualizer} options={options}>`.","If options load asynchronously, pass `options={options ?? []}` until loaded (or defer rendering the Combobox until data exists).","Remember virtual mode requires options as data, not as <ComboboxOption> children."],"exampleFix":"// before\n<Combobox virtual={virtualizer} value={value} onChange={setValue}>\n  {options.map(o => <ComboboxOption key={o.id} value={o}>...</ComboboxOption>)}\n</Combobox>\n\n// after\n<Combobox virtual={virtualizer} options={options} value={value} onChange={setValue}>\n  {opt => <div>{opt.label}</div>}\n</Combobox>","handlingStrategy":"validation","validationCode":"<Combobox virtual={virtualizer} options={options ?? []} ... >","typeGuard":"const hasOptions = (p: { options?: unknown[] }): boolean => p.options !== undefined","tryCatchPattern":null,"preventionTips":["In virtual mode always pass the options prop.","Use `options ?? []` for async data.","Don't rely on <ComboboxOption> children in virtual mode."],"tags":["headlessui","react","combobox","virtualization","missing-prop"],"backgroundTag":"missing-required-prop","analyzedSha":"eea57cf46fd6767ed1059012f7073b88eb159fba","analyzedAt":"2026-08-28T19:22:46.163Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}