---
url: "https://vueda.dev/v3/reference/api/vue/WidgetCombobox.md"
title: "WidgetCombobox"
---

# 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](/v3/reference/theming/keys/WidgetCombobox.md)

## Props

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

## Source

`client/lib/widgets/WidgetCombobox.vue`