django-autocomplete-light

Because dal_alight views return HTML fragments instead of JSON, you must adjust how you customize result labels.

Instead of overriding both get_result_label and get_selected_result_label (as required in dal_select2), you should only override the get_result_label method on dal.views.BaseQuerySetView.

An autocomplete implementation in DAL using Select2 consists of three essential components:

1. A Widget: A Django form widget compatible with the model field that handles the initial rendering.
2. JavaScript Initialization: Code that initializes the Select2 widget to trigger the autocomplete behavior.
3. An Autocomplete View: A Django view used by the widget's JavaScript to fetch suggestion results via AJAX.

Warning: Select2 has known issues with object lifecycle management in jQuery. For new projects, it is recommended to use the Autocomplete-Light Web Component instead.

When forwarding a field, DAL's JavaScript logic determines the data type sent to the server based on the following rules:

• Boolean: If there is exactly one field with the given name and it is a checkbox without an HTML value attribute, the value forwarded is a boolean indicating if it is checked.
• List of Strings:
  • If there is exactly one field with the given name and it has the multiple HTML attribute.
  • If there are one or more fields with the given name and all of them are checkboxes with an HTML value attribute (the list contains the values of the checked checkboxes).
• String: Otherwise, the field value is forwarded as a string.

DAL's Select2 integration now defines a createTag function for tags mode and marks client-created tags with newTag: true. The result template shows new tags as Create "value" while the selected value remains the raw tag text.

If you have copied or replaced autocomplete_light/select2.js, you must add equivalent handling for createTag:

var createTagFn = null;
if (use_tags) {
    createTagFn = function(params) {
        var term = $.trim(params.term);
        if (!term) return null;
        return {id: term, text: term, newTag: true};
    };
}

$element.select2({
    tags: use_tags,
    createTag: createTagFn,
    // keep your other DAL options
});

When overriding templateResult or templateSelection, you must handle item.newTag (to display the create label) and item.create_id (the server-side marker).

Choose the dal_alight frontend if your project meets any of the following criteria:

• No jQuery: You are using a modern frontend stack (like HTMX) and want to avoid jQuery.
• Minimal Payload: You want to minimize the JavaScript footprint and eliminate third-party dependencies.
• Server-Side Rendering: You prefer the server to control result rendering via HTML fragments, which is useful if labels require complex Django template logic or permission checks.
• Max-Choices Enforcement: You want client-side enforcement of a maximum number of selections (using the max-choices attribute), where the oldest selection is automatically evicted when the cap is exceeded.
• Web Components: You are building in a Custom Elements or Shadow-DOM ecosystem.

If you want to integrate an autocomplete view and form field automatically throughout Django (including the admin) without manually defining custom ModelForms every time, use the djhacker library.

import djhacker  # don't forget to pip install djhacker
from django import forms

djhacker.formfield(
    Person.birth_country,
    forms.ModelChoiceField,
    widget=autocomplete.ModelSelect2(url='country-autocomplete')
)

DAL 5.0.0 requires Django 5.2 or newer. It drops support for Django 4.2. To upgrade, upgrade Django first, then upgrade DAL without the v4 pin.

pip install -U django-autocomplete-light

Once the view is created, you must register it in your project's urlpatterns with a named URL. This name is used by the widget to know where to send AJAX requests.

from django.urls import path
from your_countries_app.views import CountryAutocomplete

urlpatterns = [
    path(
        'country-autocomplete/',
        CountryAutocomplete.as_view(),
        name='country-autocomplete',
    ),
]

To migrate an existing project from dal_select2 to dal_alight, you must replace Select2 class names with their Alight counterparts across your views, widgets, and form fields.

Key architectural changes:

• Dependency Change: dal_alight uses native Web Components and has no external library dependencies (jQuery is no longer required).
• Response Format: Unlike dal_select2 which returns JSON, dal_alight views return HTML fragments.
• Static Files: Replace dal_select2 media with dal_alight media.
• Admin: ModelAdmin.form assignment remains identical.