Select

Enhances the native <select> with search, tags and server-side search. The original element stays in the form holding the value: name, multiple, required and request.POST.getlist() work as always.

Examples

Everything below is the same <select> with different attributes.

How to use

Mark the <select> and it initializes by itself, including the ones that arrive later through HTMX. The first <option value=""> becomes the placeholder text, not an option.

<select name="state" data-tuc-select>
  <option value="">Select...</option>
  <option value="SP">São Paulo</option>
</select>

<select name="tags" data-tuc-select multiple data-placeholder="Add...">
  <option value="django">Django</option>
</select>

In the Django form

class CustomerForm(forms.ModelForm):
    class Meta:
        model = Customer
        fields = ["state", "tags"]
        widgets = {
            "state": forms.Select(attrs={"data-tuc-select": ""}),
            "tags": forms.SelectMultiple(attrs={"data-tuc-select": "", "data-max-items": "3"}),
        }

In JavaScript

For options that don't exist as attributes, or to read and write the value.

const s = new Tucano.Select('#state', { search: true, maxItems: 3 });
s.getValue();            // 'SP' — an array when multiple
s.setValue(['SP', 'PR']);
s.refresh();             // rereads the <option> elements after HTMX replaces them

Server-side search

For lists too large to come whole in the page. On every keystroke the component asks the server, instead of filtering what is already loaded.

<select name="customer" data-tuc-select data-url="{% url 'api-customers' %}"></select>

def customers(request):
    q = request.GET.get("q", "")
    qs = Customer.objects.filter(name__icontains=q)[:20]
    return JsonResponse([{"value": c.pk, "label": c.name} for c in qs], safe=False)

Value and form

The value is held by the native <select>, hidden next to the control. Django receives exactly what it would receive without the component.

POST  state = SP
POST  tags  = django    # request.POST.getlist("tags")
POST  tags  = htmx

Every choice fires tucano:change on the <select> itself, and also the native change — so HTMX's hx-trigger="change" works with no adjustment.

document.querySelector('#state').addEventListener('tucano:change', (e) => {
  e.detail.value;      // 'SP', or an array when multiple
  e.detail.instance;   // the Select
});

Keyboard and accessibility

The control is a combobox with a listbox, and announces open, closed and the active option. Arriving with Tab doesn't open the panel — that's the rule of the native <select>.

API

Generated from the code on every build — if something is not here, it does not exist.

Options

The notes in this table come from comments in the source code, which are written in Portuguese.