Select

Partial Input

Kumo-styled Alpine dropdown with groups, rich options and multiple selection; native form values and fallback.

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

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

Basic

Favorite fruit

Show template

{% load wdj %}
<div class="w-[200px] max-w-full">
{% include "wdj/components/select.html" with id="select_basic" name="select_basic" options=audit_select_fruits label="Favorite fruit" selected="apple" only %}
</div>

Placeholder

Label

Environment

Show template

{% load wdj %}
<div class="grid w-full max-w-lg gap-4">
{% include "wdj/components/select.html" with name="select_label" options=environments label="Environment" only %}
</div>

Description

Issue type

Choose the category that best describes your issue

Issue type

Choose the category that best describes your issue

Show template

{% load wdj %}
<div class="w-[280px] max-w-full">{% include "wdj/components/select.html" with name="select_description" label="Issue type" description="Choose the category that best describes your issue" options=select_issues placeholder="Select an option" only %}</div>

Selected value

Environment

Show template

{% load wdj %}
<div class="grid w-full max-w-lg gap-4">
{% include "wdj/components/select.html" with name="select_selected_value" options=environments selected="staging" label="Environment" only %}
</div>

Required

Environment

Show template

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

Disabled

Environment

Show template

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

Error

Issue type

Please select an issue type

Issue type

Please select an issue type

Show template

{% load wdj %}
<div class="w-[280px] max-w-full">{% include "wdj/components/select.html" with name="select_error" label="Issue type" error="Please select an issue type" options=select_issues placeholder="Select an option" only %}</div>

Groups

Region

Show template

{% load wdj %}
<div class="grid w-full max-w-lg gap-4">
{% include "wdj/components/select.html" with name="select_groups" options=grouped_options label="Region" only %}
</div>

Small

Show template

{% load wdj %}
<div class="grid w-full max-w-lg gap-4">
{% include "wdj/components/select.html" with name="select_small" options=environments label="Small" size="sm" only %}
</div>

Large

Show template

{% load wdj %}
<div class="grid w-full max-w-lg gap-4">
{% include "wdj/components/select.html" with name="select_large" options=environments label="Large" size="lg" only %}
</div>

Plain options

Region

Show template

{% load wdj %}
<div class="grid w-full max-w-lg gap-4">
{% include "wdj/components/select.html" with name="select_plain_options" options=regions label="Region" only %}
</div>

Native fallback

Native environment

Show template

{% load wdj %}
<div class="grid w-full max-w-lg gap-4">
  {% include "wdj/components/select.html" with mode="native" name="select_native" label="Native environment" options=environments only %}
</div>

Placement

side=bottom (default)

side=top

align=end

sideOffset=12

Show template

{% load wdj %}
<div class="grid w-full justify-items-center gap-4 sm:grid-cols-2">
<div class="w-[200px] max-w-full">{% include "wdj/components/select.html" with id="select-bottom" label="side=bottom (default)" selected="earth" options=select_planets only %}</div>
<div class="w-[200px] max-w-full">{% include "wdj/components/select.html" with id="select-top" label="side=top" selected="earth" options=select_planets side="top" only %}</div>
<div class="w-[200px] max-w-full">{% include "wdj/components/select.html" with id="select-end" label="align=end" selected="earth" options=select_planets align="end" only %}</div>
<div class="w-[200px] max-w-full">{% include "wdj/components/select.html" with id="select-offset" label="sideOffset=12" selected="earth" options=select_planets side_offset=12 only %}</div>
</div>

Custom value rendering

Language

Show template

{% load wdj %}
<div class="w-[200px] max-w-full">{% include "wdj/components/select.html" with id="select-language" name="language" label="Language" selected="en" options=select_languages only %}</div>

Author with rich options

Author

Select the primary author for this document

Author

Select the primary author for this document

Show template

{% load wdj %}
<div class="w-[200px] max-w-full">{% include "wdj/components/select.html" with id="select-author" name="author" label="Author" description="Select the primary author for this document" placeholder="Select an author" options=select_authors only %}</div>

Disabled items

Plan

Show template

{% load wdj %}
<div class="w-[200px] max-w-full">{% include "wdj/components/select.html" with id="select-plan" label="Plan" selected="free" options=select_plans only %}</div>

Groups with disabled options

Server region

Show template

{% load wdj %}
<div class="w-[260px] max-w-full">{% include "wdj/components/select.html" with id="select-regions" name="region" label="Server region" placeholder="Select a region..." options=select_regions only %}</div>

Loading from server

Assignee

Show template

{% load wdj %}
<div id="select-async" class="w-[200px] max-w-full" hx-get="{% url 'showcase:select_assignees' %}" hx-trigger="load delay:2s" hx-swap="outerHTML">{% include "wdj/components/select.html" with id="select-assignee" label="Assignee" loading=True only %}</div>

Custom popup

Environment

Show template

{% load wdj %}
{% include "wdj/components/select.html" with mode="custom" id="audit-select-custom-popup" name="environment" label="Environment" options=audit_options only %}

Popup sizes

base

Show template

{% load wdj %}
<div class="grid w-[244px] max-w-full gap-4">{% for size in audit_sizes %}<div class="flex items-center gap-3"><span class="w-10 shrink-0 text-base text-kumo-subtle">{{ size }}</span>{% include "wdj/components/select.html" with id="audit-select-size-"|add:size aria_label="Select size "|add:size size=size options=audit_select_fruits placeholder="Choose..." only %}</div>{% endfor %}</div>

Top placement

Environment

Show template

{% load wdj %}
{% include "wdj/components/select.html" with mode="custom" id="audit-select-top-placement" name="environment" label="Environment" side="top" options=audit_options only %}

Rich option rendering

Environment

Show template

{% load wdj %}
{% include "wdj/components/select.html" with mode="custom" id="audit-select-rich-option-rendering" name="environment" label="Environment" options=audit_options only %}

Loading popup

Environment

Show template

{% load wdj %}
{% include "wdj/components/select.html" with mode="custom" id="audit-select-loading-popup" name="environment" label="Environment" loading=True options=audit_options only %}

Multiple popup choices

Visible columns

Show template

{% load wdj %}
<div class="w-[250px] max-w-full">{% include "wdj/components/select.html" with id="select-columns" name="columns" label="Visible columns" multiple=True options=select_columns selected_values=select_initial_columns max_display_items=3 placeholder="Select columns..." only %}</div>

Grouped popup options

Food

Show template

{% load wdj %}
<div class="w-[220px] max-w-full">{% include "wdj/components/select.html" with id="select-food" name="food" label="Food" options=select_foods placeholder="Pick a food..." only %}</div>

Long popup list

Show template

{% load wdj %}
{% include "wdj/components/select.html" with mode="custom" id="audit-select-long-popup-list" name="environment" label="Environment" options=audit_long_options only %}

Popup validation and reset

Show template

{% load wdj %}
<form data-demo-form class="flex flex-col gap-3">{% include "wdj/components/select.html" with mode="custom" id="audit-select-form" name="environment" options=audit_options label="Environment" placeholder="Choose an environment" required=True only %}<div class="flex gap-2">{% include "wdj/components/button.html" with type="submit" label="Validate selection" only %}{% include "wdj/components/button.html" with type="reset" label="Reset selection" only %}</div></form>

Popup error

Environment

Choose an available environment.

Environment

Choose an available environment.

Show template

{% load wdj %}
{% include "wdj/components/select.html" with mode="custom" id="audit-select-error" name="environment" label="Environment" options=audit_options error="Choose an available environment." only %}

Popup without visible label

Show template

{% load wdj %}
<div class="w-[200px] max-w-full">{% include "wdj/components/select.html" with id="select-bare" name="fruit" aria_label="Select a fruit" options=audit_select_fruits selected="apple" only %}</div>

Selected option alignment

Anchored (default)

Opens below the trigger

Anchored (default)

Opens below the trigger

Aligned to selection

Selected option lands on the trigger

Aligned to selection

Selected option lands on the trigger

Show template

{% load wdj %}
<div class="flex w-full flex-wrap justify-center gap-8">
<div class="w-[200px] max-w-full">{% include "wdj/components/select.html" with id="select-anchored" label="Anchored (default)" description="Opens below the trigger" options=select_planets selected="mars" only %}</div>
<div class="w-[200px] max-w-full">{% include "wdj/components/select.html" with id="select-aligned" label="Aligned to selection" description="Selected option lands on the trigger" options=select_planets selected="mars" align_selected=True only %}</div>
</div>

Popup label tooltip

Environment

Show template

{% load wdj %}
{% include "wdj/components/select.html" with mode="custom" id="audit-select-tooltip" name="environment" label="Environment" label_tooltip="Choose where this project runs." options=audit_options only %}

Popup in a clipped container

Environment

Show template

{% load wdj %}
<div class='h-20 overflow-hidden rounded-xl bg-kumo-fill p-3' style='transform:translateZ(0)'>
  {% include 'wdj/components/select.html' with id='clipped-popup' name='environment' mode='custom' label='Environment' options=audit_options selected='prod' only %}
</div>

API Reference

Prop	Type	Default	Description
mode	string	custom	Select: custom Alpine popup by default; native explicitly requests the platform picker. Tabs has its own local/navigation contract.
name	string	unset	Name; 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.
selected	string	unset	Initial server selection: one value, a list for multiple=True, or selected flags on native options.
selected_values	list[dict]	unset	Selected values; pass the documented value shown in the examples.
placeholder	string	unset	Placeholder; 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.
optional	bool	False	Optional; pass the documented value shown in the examples.
label_tooltip	string	unset	Label tooltip; 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.
multiple	bool	False	Multiple; pass the documented value shown in the examples.
visible_options	string	unset	Visible options; pass the documented value shown in the examples.
size	string	base	Size; pass the documented value shown in the examples.
variant	string	component-specific	Variant; pass the documented value shown in the examples.
id	string	unset	Stable unique DOM ID; important for HTMX targets and focus restoration.
attrs	dict	{}	Dictionary of escaped native, HTMX or Alpine attributes. Literal Tailwind classes only.
field_class	string	unset	Field class; pass the documented value shown in the examples.
side	string	bottom	Side; pass the documented value shown in the examples.
align	string	start	Align; pass the documented value shown in the examples.
side_offset	string	unset	Side offset; pass the documented value shown in the examples.
align_offset	string	unset	Align offset; pass the documented value shown in the examples.
loading	bool	False	Loading; pass the documented value shown in the examples.
align_selected	bool	False	Align selected; pass the documented value shown in the examples.
max_display_items	string	unset	Max display items; pass the documented value shown in the examples.
display_summary	string	unset	Display summary; pass the documented value shown in the examples.
searchable	bool	False	Select: show a search field inside the popup, with case- and accent-insensitive filtering.
search_placeholder	string	unset	Search placeholder; pass the documented value shown in the examples.
empty_message	string	unset	Empty message; pass the documented value shown in the examples.
trigger_variant	string	unset	Searchable button: default control styling or ghost.

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