Combobox / Autocomplete

Partial Input

Kumo-styled input/button triggers, search inside the popup, grouped local choices and debounced HTMX search.

Kumo reference: kumo-ui.com/components/combobox/

Presentation commands show demo feedback. Read the interaction guide to connect real actions.

Basic

Show template

{% load wdj %}
<div class="w-160 max-w-full">
  {% include "wdj/components/combobox.html" with id="combobox_fruits" name="fruit" options=audit_fruits value="Apple" placeholder="Please select" aria_label="Favorite fruit" only %}
</div>

Server search

Type a query, then use Arrow keys and Enter to choose a result.

Project

Show template

{% load wdj %}
<div class="grid w-full max-w-lg gap-4">
{% include "wdj/components/combobox.html" with id="combobox_server_search" name="q" label="Project" endpoint="/combobox/options/" only %}
</div>

Local filtering

Project

Show template

{% load wdj %}
<div class="grid w-full max-w-lg gap-4">
{% include "wdj/components/combobox.html" with id="combobox_local_filtering" name="q" label="Project" options=environments only %}
</div>

Initial options

Project

Show template

{% load wdj %}
<div class="grid w-full max-w-lg gap-4">
{% include "wdj/components/combobox.html" with id="combobox_initial_options" name="q" label="Project" options=environments endpoint="/combobox/options/" only %}
</div>

Selected value

Project

Show template

{% load wdj %}
<div class="grid w-full max-w-lg gap-4">
{% include "wdj/components/combobox.html" with id="combobox_selected_value" name="q" label="Project" options=environments value="staging" only %}
</div>

Empty result

Project

Show template

{% load wdj %}
<div class="grid w-full max-w-lg gap-4">
{% include "wdj/components/combobox.html" with id="combobox_empty_result" name="q" label="Project" options=environments only %}
</div>

Disabled

Project

Show template

{% load wdj %}
<div class="grid w-full max-w-lg gap-4">
{% include "wdj/components/combobox.html" with id="combobox_disabled" name="q" label="Project" options=environments disabled=True only %}
</div>

Error

Project

Select a project.

Show template

{% load wdj %}
<div class="grid w-full max-w-lg gap-4">
{% include "wdj/components/combobox.html" with id="combobox_error" name="q" label="Project" endpoint="/combobox/options/" error="Select a project." only %}
</div>

Required

Project

Show template

{% load wdj %}
<div class="grid w-full max-w-lg gap-4">
{% include "wdj/components/combobox.html" with id="combobox_required" name="q" label="Project" options=environments required=True only %}
</div>

Multiple selection

Projects

productionedge-workercloudflare

Show template

{% load wdj %}
{% include "wdj/components/combobox.html" with id="combobox_multiple_selection" label="Projects" options=environments multiple=True name="projects" selected_values=initial_tags only %}

Description

Projects

Choose a deployment environment.

Show template

{% load wdj %}
{% include "wdj/components/combobox.html" with id="combobox_description" label="Projects" options=environments name="q" description="Choose a deployment environment." only %}

Custom placeholder

Projects

Show template

{% load wdj %}
{% include "wdj/components/combobox.html" with id="combobox_custom_placeholder" label="Projects" options=environments name="q" placeholder="Find a project" only %}

Disabled options

Projects

Show template

{% load wdj %}
{% include "wdj/components/combobox.html" with id="combobox_disabled_options" label="Projects" name="q" options=environments only %}

Keyboard navigation

Projects

Show template

{% load wdj %}
{% include "wdj/components/combobox.html" with id="combobox_keyboard_navigation" label="Projects" name="q" options=environments only %}

Searchable item (inside)

Show template

{% load wdj %}
<div class="flex flex-wrap items-start gap-4">
  <div class="w-40 max-w-full">{% include 'wdj/components/combobox.html' with id='popup-language-small' name='language-small' options=popup_languages value='en' trigger_label='Select a language' size='sm' labels=popup_search_labels only %}</div>
  <div class="w-45 max-w-full">{% include 'wdj/components/combobox.html' with id='popup-language-base' name='language' options=popup_languages value='cs' trigger_label='Select a language' labels=popup_search_labels only %}</div>
</div>

Searchable select with placeholder

Show template

{% load wdj %}
<div class="w-50 max-w-full">{% include 'wdj/components/combobox.html' with id='popup-language-empty' name='language' options=popup_languages trigger_label='Select a language' labels=popup_search_labels only %}</div>

Custom trigger

Show template

{% load wdj %}
<div class="w-50 max-w-full">{% include 'wdj/components/combobox.html' with id='popup-language-ghost' name='language' options=popup_languages_custom value='en' trigger_label='Select a language' trigger_variant='ghost' size='sm' labels=popup_search_labels only %}</div>

Searchable popup groups

Environment

Show template

{% load wdj %}
<div class="w-64 max-w-full">{% include 'wdj/components/combobox.html' with id='popup-grouped' name='environments' options=audit_grouped_options trigger_label='Select an environment' label='Environment' only %}</div>

All sizes

base

Show template

{% load wdj %}
{% for size in audit_sizes %}{% include "wdj/components/combobox.html" with id="audit-combobox-size-"|add:size name="q" label=size size=size options=audit_options only %}{% endfor %}

Grouped rich options

Environment

Show template

{% load wdj %}
{% include "wdj/components/combobox.html" with id="audit-combobox-grouped" label="Environment" options=audit_options only %}

Controlled local value

Environment

Show template

{% load wdj %}
<div x-data="{ value: '' }">{% include "wdj/components/combobox.html" with id="audit-combobox-controlled" label="Environment" options=audit_options attrs=audit_combo_model only %}<p class="mt-2 text-base" x-text="value"></p></div>

Required chips beside search

Show template

{% load wdj %}
<form class='flex flex-col gap-3' action='#' data-demo-form>
  {% include 'wdj/components/combobox.html' with id='required-chip-search' name='environments' label='Medii' labels=audit_combo_labels options=audit_options multiple=True input_side='right' required=True min_chars=0 only %}
  <div class='flex flex-wrap gap-2'>{% include 'wdj/components/button.html' with label='Salvează mediile' type='submit' only %}{% include 'wdj/components/button.html' with label='Resetează mediile' type='reset' only %}</div>
</form>

API Reference

Prop	Type	Default	Description
id	string	unset	Stable unique DOM ID; important for HTMX targets and focus restoration.
name	string	unset	Name; pass the documented value shown in the examples.
value	string	unset	Value; pass the documented value shown in the examples.
label	string	unset	Visible accessible label. Supply an explicit aria-label via attrs when the control is bare.
aria_label	string	unset	Aria label; pass the documented value shown in the examples.
description	string	unset	Description; pass the documented value shown in the examples.
error	string	unset	Validation message; implies error styling and accessible error association.
required	bool	False	Required; pass the documented value shown in the examples.
disabled	bool	False	Disabled; pass the documented value shown in the examples.
placeholder	string	unset	Placeholder; pass the documented value shown in the examples.
endpoint	string	unset	Application-owned server endpoint; dynamic HTMX fragments use no-store and Vary: HX-Request.
delay	string	300ms	Delay; pass the documented value shown in the examples.
min_chars	number	1	Min chars; pass the documented value shown in the examples.
options	list[dict]	[]	Select: value/label/display_label/disabled/selected or groups with options. Combobox input: value/label/disabled/group/icon/description; button search also supports Select groups.
multiple	bool	False	Multiple; pass the documented value shown in the examples.
selected_values	list[dict]	unset	Selected values; pass the documented value shown in the examples.
input_side	string	unset	Multiple Combobox: top (default) or right; right places the search beside chips and wraps on small screens.
size	string	base	Size; pass the documented value shown in the examples.
labels	dict	{}	Escaped text overrides: search_placeholder, list_label, empty_message, required_message, remove_label, clear_selection and show_options. Explicit placeholder takes precedence over search_placeholder; remote empty messages come from the endpoint.
attrs	dict	{}	Dictionary of escaped native, HTMX or Alpine attributes. Literal Tailwind classes only.
trigger_label	string	unset	Combobox without endpoint: enable the button trigger and search inside its popup. Calendar: calendar trigger text.
trigger_variant	string	unset	Searchable button: default control styling or ghost.
freeform	bool	False	Omit the dropdown trigger for an editable Autocomplete input. Filtering, keyboard selection and typed form values remain available.
field_class	string	unset	Field class; pass the documented value shown in the examples.

Accessibility notes

Every interactive component keeps real semantics and keyboard support: native controls where possible, ARIA only where necessary, and a visible focus ring. See the Accessibility page for the shared contract.

Read the accessibility contract