# ComboboxPopover - Page: https://jiguang132.com/resources/mantine/docs/combobox-popover - Resource: Mantine Core (https://jiguang132.com/resources/mantine.md) - All guides: https://jiguang132.com/resources/mantine/docs.md Install: `npm install @mantine/core@9.7.1 @mantine/hooks@9.7.1` ## Version and compatibility Pinned Mantine Core 9.7.1 requires React and React DOM `^19.2.0` and matching `@mantine/hooks@9.7.1`, from the installed npm package's peerDependencies. Do not force it into React 18 or another incompatible version. Explain upgrade impact and agree on a plan with the project owner; do not hide conflicts with --force/--legacy-peer-deps. The native Provider enables `theme.respectReducedMotion` and uses `forceColorScheme` for light/dark. ## Use case Compose a searchable selection inside a popover. ## Native props used by this example These props are extracted from the local typechecked JSX and grouped by their owning native component. This is not an exhaustive prop list; see pinned source signatures and inheritance below. | Component prop | Explanation | | --- | --- | | `ComboboxPopover.data` | Local options/nodes; keep unique values and native schema. | | `ComboboxPopover.searchable` | Enable this component's local search interaction. | | `ComboboxPopover.value` | Controlled value; the native type defines its shape. | | `ComboboxPopover.onChange` | Native value/event callback; preserve its actual signature. | ## Interaction and state checks Current scenarios: Default. Check actual behavior after selecting supported disabled/error/read-only scenarios; components without those native states do not receive invented universal props. Verify keyboard focus and exits, then connect changed values through the native callback signature. ## Business integration boundary Target must accept the trigger's forwarded props/ref. Search is local unless the host supplies remote data. ## Host setup Install pinned @mantine/core and @mantine/hooks, import @mantine/core/styles.css at the entry and use MantineProvider. The example's theme/variant are JGuang-authored host props, not universal native component APIs; forceColorScheme synchronizes the app theme. Native implementation source is a reading reference: use npm exports rather than copying internal engines. This batch covers Core, not dates/charts/forms extension packages. Detailed upstream prose remains English. ## Runnable usage ```tsx import { useState } from 'react'; import * as M from '@mantine/core'; import '@mantine/core/styles.css'; const fruit = ["Apple", "Banana", "Orange"]; function ComponentPreview({ variant = 'Default' }: { variant?: string }) { const [value, setValue] = useState(35); const [selection, setSelection] = useState(null); return {selection ?? "Choose a fruit / 选择水果"}; } export default function Example({ variant = 'Default', theme = 'light' }: { variant?: string; theme?: 'light' | 'dark' }) { return ; } ``` ## Preview states Default The example uses the native Mantine API. For supported input demos, change the local variant to Disabled, Invalid or Read only; these are example labels, not new component props. Keep the documented data, controlled values, stores and compound children when adapting the example. ## Usage `ComboboxPopover` adds a dropdown with selectable options to any button. Unlike `Select` and `MultiSelect`, it does not render an input: pass your own target element to `ComboboxPopover.Target`. The target must be a single element or component that accepts a `ref`. ## Data format `ComboboxPopover` supports the same `data` format as [Select](/core/select) component: an array of strings, objects with `value` and `label`, or grouped items. ## Searchable Set `searchable` prop to add a search input to the dropdown: ## Controlled search value Use `searchValue` and `onSearchChange` props to control the search input value: ## Sort options Use `filter` prop with `searchable` to provide a custom filtering and sorting function: ## Limit options Use `limit` prop with `searchable` to limit the number of options displayed at a time: ## Multiple selection Set `multiple` prop to allow selecting multiple values. `value` type changes from `string | null` to `string[]`. ## Check icon ## Allow deselect By default, the selected option can be deselected by clicking it again. Set `allowDeselect={false}` to prevent this behavior. ## Nothing found message Set `nothingFoundMessage` prop to display a message when no options are available: ## Disabled options ## Groups ## Render option Use `renderOption` prop to customize option rendering: ## Large data sets By default, the dropdown is wrapped with `ScrollArea.Autosize`. Use `maxDropdownHeight` to control the maximum height: ## Control dropdown opened state Use `dropdownOpened`, `onDropdownOpen` and `onDropdownClose` props to control the dropdown state: ## Dropdown position ## Dropdown width By default, the dropdown width matches the target element. Use `comboboxProps` to set a custom width: ## Dropdown animation ## Form submission `ComboboxPopover` renders a hidden input with the selected value for native form submission. Use `name` prop to set the input name. For multiple selection, values are joined with a comma by default – use `hiddenInputValuesDivider` to change the separator. ## Source-backed parameter reference Implementation signatures and types are generated from the pinned local source. Optional props, native inherited types, union branches and never exclusions are preserved. A forwardRef implementation's ref is a React reference, not an additional business prop. ```ts ComboboxPopover(_props) ``` ```ts export type ComboboxPopoverStylesNames = ComboboxLikeStylesNames | 'search'; export interface ComboboxPopoverProps< Multiple extends boolean = false, Value extends Primitive = string, > extends StylesApiProps { /** If set, multiple items can be selected at the same time */ multiple?: Multiple; /** Controlled component value */ value?: ComboboxPopoverValue; /** Uncontrolled component default value */ defaultValue?: ComboboxPopoverValue; /** Called when value changes */ onChange?: (value: ComboboxPopoverValue) => void; /** Data used to generate options */ data?: ComboboxData; /** Controlled dropdown opened state */ dropdownOpened?: boolean; /** Uncontrolled dropdown initial opened state */ defaultDropdownOpened?: boolean; /** Called when dropdown opens */ onDropdownOpen?: () => void; /** Called when dropdown closes */ onDropdownClose?: () => void; /** Called when option is submitted from dropdown with mouse click or Enter key */ onOptionSubmit?: (value: Value) => void; /** Props passed down to Combobox component */ comboboxProps?: ComboboxProps; /** Function based on which items are filtered and sorted */ filter?: OptionsFilter; /** Maximum number of options displayed at a time @default Infinity */ limit?: number; /** Determines whether the options should be wrapped with ScrollArea.AutoSize @default true */ withScrollArea?: boolean; /** max-height of the dropdown @default 220 */ maxDropdownHeight?: number | string; /** If set, the first option is selected when dropdown opens @default false */ selectFirstOptionOnDropdownOpen?: boolean; /** Displays check icon near the selected option label @default true */ withCheckIcon?: boolean; /** Aligns unchecked labels with the checked one @default false */ withAlignedLabels?: boolean; /** Position of the check icon relative to the option label @default 'left' */ checkIconPosition?: 'left' | 'right'; /** Message displayed when no options match the search query or when there is no data */ nothingFoundMessage?: React.ReactNode; /** Allows searching through options @default false */ searchable?: boolean; /** Controlled search value */ searchValue?: string; /** Default search value */ defaultSearchValue?: string; /** Called when search changes */ onSearchChange?: (value: string) => void; /** Allows deselecting the selected option by clicking it (only for single mode) @default true */ allowDeselect?: boolean; /** A function to render content of the option, replaces the default content of the option */ renderOption?: (item: ComboboxLikeRenderOptionInput) => React.ReactNode; /** Props passed down to the underlying ScrollArea component in the dropdown */ scrollAreaProps?: ScrollAreaProps; /** Props passed down to the hidden input */ hiddenInputProps?: Omit, 'value'>; /** Hidden input name for form submission */ name?: string; /** Hidden input form for form submission */ form?: string; /** Content of the component */ children?: React.ReactNode; /** Divider used to separate values in the hidden input value attribute @default ',' */ hiddenInputValuesDivider?: string; } export type ComboboxPopoverFactory = Factory<{ props: ComboboxPopoverProps; ref: HTMLDivElement; stylesNames: ComboboxPopoverStylesNames; signature: ( props: ComboboxPopoverProps ) => React.JSX.Element; staticComponents: { Target: typeof ComboboxPopoverTarget; }; }>; ``` ### Native and external types External types remain defined by React or native dependencies, not manually expanded into guessed props. The installed version's TypeScript definitions are authoritative. ```ts Factory<{ props: ComboboxPopoverProps; ref: HTMLDivElement; stylesNames: ComboboxPopoverStylesNames; signature: ( props: ComboboxPopoverProps ) => React.JSX.Element; staticComponents: { Target: typeof ComboboxPopoverTarget; }; }> Primitive StylesApiProps Multiple ComboboxPopoverValue Value ComboboxData ComboboxProps OptionsFilter React.ReactNode ComboboxLikeRenderOptionInput ComboboxItem ScrollAreaProps Omit, 'value'> React.ComponentProps<'input'> HTMLDivElement ComboboxLikeStylesNames React.JSX.Element ``` --- Index of all JGuang resources: https://jiguang132.com/llms.txt