Migrating from dal_select2 to dal_alight¶

This guide helps you migrate an existing dal_select2 project to dal_alight. It’s not a requirement, but it’s supposed to be doable.

Why migrate¶

dal_select2 depends on jQuery, which puts the developer in charge of the JavaScript object lifecycle. dal_alight uses native Web Components with no external library dependency — no jQuery required.

Class name mapping¶

Replace Select2 with its Alight counterpart in your views, widgets, and form fields.

Views¶
`dal_select2`	`dal_alight`
`Select2QuerySetView`	`AlightQuerySetView`
`Select2GroupQuerySetView`	`AlightGroupQuerySetView`
`Select2ListView`	`AlightListView`
`Select2GroupListView`	`AlightGroupListView`
`Select2QuerySetSequenceView`	`AlightQuerySetSequenceView`

Widgets¶
`dal_select2`	`dal_alight`
`ModelSelect2`	`ModelAlight`
`ModelSelect2Multiple`	`ModelAlightMultiple`
`Select2`	`ListAlight`
`Select2Multiple`	`ModelAlightMultiple` or `TagAlight`
`ListSelect2`	`ListAlight`
`TagSelect2`	`TagAlight`
`TaggitSelect2`	`TaggitAlight`
`QuerySetSequenceSelect2`	`QuerySetSequenceAlight`
`QuerySetSequenceSelect2Multiple`	`QuerySetSequenceAlightMultiple`

Form fields¶
`dal_select2`	`dal_alight`
`Select2ListChoiceField`	`AlightListChoiceField`
`Select2ListCreateChoiceField`	`AlightListCreateChoiceField`
`Select2GenericForeignKeyModelField`	`AlightGenericForeignKeyModelField`

Behavioural differences¶

Response format: Select2 views return JSON; alight views return HTML fragments. Override get_result_label() instead of get_result_label + get_selected_result_label.
Create: the POST response returns an HTML label fragment, not {"id": …, "text": …} JSON.
Forwarding: the forward widget argument and dal.forward helpers work identically.
Admin registration: ModelAdmin.form assignment works identically.
Static files: replace dal_select2 media with dal_alight media; jQuery is no longer loaded by the widget.

Changes in 5.1¶

Since 5.1.0 (see CHANGELOG):

Widget attrs apply to the visible search <input>, not a hidden <select>.
ListAlight now requires a url; client-side local filtering of static choices was removed. Use ListAlight with AlightListView, or a plain <select> for tiny static lists.
The change event fires on <autocomplete-select>, not a <select>.
Alight and AlightMultiple were removed; use the widget mapping table above (Select2 → ListAlight; Select2Multiple → ModelAlightMultiple or TagAlight).