WidgetCombobox

Overview

A combobox widget supporting static options or API-backed search, single or multiple selection, grouping, and read-only display. Replaces WidgetSearchableSelect, WidgetAutoComplete, and WidgetMultiSelect.

Provide either options (static mode) or both app and model (API mode). The multiple prop works in both modes.

Theme entry: WidgetCombobox

Props

Name	Type	Required	Default	Description
iconOverride	Object		null	A partial icon registry ({ [componentName]: { [iconName]: { component, props } } }) merged with inherited and default icon entries; scopes icon overrides to this component and its descendants.
themeOverride	String|Object|Array		null	A partial theme object merged with the component's default theme; accepts a class string, class array, or theme object.
name	String		undefined	The widget name; falls back to the field context value when omitted.
label	String		undefined	The label displayed next to the widget; falls back to the field context value when omitted.
help	String		undefined	Help text displayed alongside the widget; falls back to the field context value when omitted.
readOnly	Boolean		false	Whether the widget is read-only; falls back to the field context value when omitted.
required	Boolean		undefined, // let the default from field context take over	Whether the widget is required; falls back to the field context value when undefined.
modelValue	String|Number|Boolean|Array|Object		undefined	The widget's bound value (v-model); used only in contextless mode.
fieldToWidget	Object|Function		null	Adapter that converts the form model value into a value suitable for the widget UI.
widgetToField	Object|Function		null	Adapter that converts the widget UI value back into a form model value for validation and submission.
invalid	Boolean		undefined	Manually set the invalid state when not in a field context.
warning	Boolean		undefined	Manually set the warning state when not in a field context.
disabled	Boolean		false	Whether the widget is disabled.
disabledFn	Function		null	A function that returns whether the widget should be disabled; takes precedence over the disabled prop.
contextless	Boolean		false	When true, the widget ignores any surrounding field or form context and manages its own state.
displayDependencies	Array		() => []	Field paths whose values the widget needs for display logic; registered with the field context.
options	array		undefined	Static option array. When provided, filtering is handled client-side via useFilter.
app	string		undefined	Django app label for the model to search (API mode).
model	string		undefined	Django model name (API mode).
modelFields	array		[]	Additional field names to include in each API result (API mode).
modelExpandFields	array		[]	Field names to expand in each API result (API mode).
modelOrdering	array		[]	Default ordering for API results (API mode).
multiple	boolean		false	Whether multiple values can be selected.
optionLabel	string		"formatted_name"	Field name on each option object to use as the displayed label in the search list.
optionValue	string		"value"	Field name on each option object to use as the submitted value (static mode).
selectedOptionLabel	string		"formatted_name"	Field name on each resolved object to display when the combobox is closed (API mode).
readonly	boolean		false	Whether the widget is in read-only mode.
placeholder	string		undefined	Placeholder text shown when no value is selected.
extraParams	object		{}	Extra query parameters merged into every API request (API mode).
getExtraParams	func		undefined	Function returning additional parameters from field dependency values (API mode).
grouped	boolean		false	Whether to group API results by a field (API mode).
groupBy	string		undefined	Field name to group results by (API mode). Requires grouped: true.

Events

Name	Description
update:modelValue	Emitted when the widget value changes.

Full event reference

Source

client/lib/widgets/WidgetCombobox.vue