Autocomplete

Implemented Input

Free-form input with local or HTMX-filtered suggestions.

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

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 freeform=True id="autocomplete_fruits" name="fruit" options=audit_fruits placeholder="Search fruits…" aria_label="Search fruits" 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 freeform=True id="autocomplete_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 freeform=True id="autocomplete_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 freeform=True id="autocomplete_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 freeform=True id="autocomplete_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 freeform=True id="autocomplete_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 freeform=True id="autocomplete_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 freeform=True id="autocomplete_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 freeform=True id="autocomplete_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 freeform=True id="autocomplete_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 freeform=True id="autocomplete_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 freeform=True id="autocomplete_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 freeform=True id="autocomplete_disabled_options" label="Projects" name="q" options=environments only %}

Keyboard navigation

Projects

Show template

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

All sizes

base

Show template

{% load wdj %}
{% for size in audit_sizes %}{% include "wdj/components/combobox.html" with freeform=True id="audit-autocomplete-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 freeform=True id="audit-autocomplete-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 freeform=True id="audit-autocomplete-controlled" label="Environment" options=audit_options attrs=audit_combo_model only %}<p class="mt-2 text-base" x-text="value"></p></div>

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