Quick start: adding simple autocompletes

This tutorial guides you through the process of enabling autocomplete for a simple form. We’ll enable autocompletion for Person on the form of an Order model, i.e. we want to get autocompletion for Person objects when we type the person’s first or last name.

For this to work, we have to register an autocomplete for the Person model. The autocomplete tells autocomplete-light how to render your autocompletion and what model fields to search in (like first_name, last_name, ...).

When we have defined how a Person autocompletion should look like, we have to enable it in the Order form. This is done by modifying the Order form so that autocomplete-light’s special form fields are used instead of the ones built into Django. autocomplete-light provides a handy wrapper around Django’s modelforms which makes this a very easy thing to do.

autocomplete_light.register() shortcut to generate and register Autocomplete classes

Register an Autocomplete for your model in your_app/autocomplete_light_registry.py, it can look like this:

import autocomplete_light.shortcuts as al
from models import Person

# This will generate a PersonAutocomplete class.
    # Just like in ModelAdmin.search_fields.
    search_fields=['^first_name', 'last_name'],
        # This will set the input placeholder attribute:
        'placeholder': 'Other model name ?',
        # This will set the yourlabs.Autocomplete.minimumCharacters
        # options, the naming conversion is handled by jQuery.
        'data-autocomplete-minimum-characters': 1,
    # This will set the data-widget-maximum-values attribute on the
    # widget container element, and will be set to
    # yourlabs.Widget.maximumValues (jQuery handles the naming
    # conversion).
        'data-widget-maximum-values': 4,
        # Enable modern-style widget !
        'class': 'modern-style',


If using Django >= 1.7, you might as well do register() calls directly in your AppConfig.ready() as demonstrated in the example app: autocomplete_light.example_apps.app_config_without_registry_file.

AutocompleteView.get() can proxy PersonAutocomplete.autocomplete_html() because PersonAutocomplete is registered. This means that openning /autocomplete/PersonAutocomplete/ will call AutocompleteView.get() which will in turn call PersonAutocomplete.autocomplete_html().

digraph autocomplete {
"widget HTML" -> "widget JavaScript" -> "AutocompleteView" -> "autocomplete_html()";

Also AutocompleteView.post() would proxy PersonAutocomplete.post() if it was defined. It could be useful to build your own features like on-the-fly object creation using Javascript method overrides like the remote autocomplete.


Note that this would make all Person public. Fine tuning security is explained later in this tutorial in section Overriding the queryset of a model autocomplete to secure an Autocomplete.

autocomplete_light.register() generates an Autocomplete class, passing the extra keyword arguments like AutocompleteModel.search_fields to the Python type() function. This means that extra keyword arguments will be used as class attributes of the generated class. An equivalent version of the above code would be:

class PersonAutocomplete(autocomplete_light.AutocompleteModelBase):
    search_fields = ['^first_name', 'last_name']
    model = Person


If you wanted, you could override the default AutocompleteModelBase used by autocomplete_light.register() to generate Autocomplete classes.

It could look like this (in your project’s urls.py):

autocomplete_light.registry.autocomplete_model_base = YourAutocompleteModelBase

Refer to the Autocomplete classes documentation for details, it is the first chapter of the the reference documentation.

autocomplete_light.modelform_factory() shortcut to generate ModelForms in the admin

First, ensure that scripts are installed in the admin base template.

Then, enabling autocompletes in the admin is as simple as overriding ModelAdmin.form in your_app/admin.py. You can use the modelform_factory() shortcut as such:

class OrderAdmin(admin.ModelAdmin):
    # This will generate a ModelForm
    form = autocomplete_light.modelform_factory(Order, fields='__all__')

Refer to the Form, fields and widgets documentation for other ways of making forms, it is the second chapter of the the reference documentation.

autocomplete_light.ModelForm to generate Autocomplete fields, the DRY way

First, ensure that scripts are properly installed in your template.

Then, you can use autocomplete_light.ModelForm to replace automatic Select and SelectMultiple widgets which renders <select> HTML inputs by autocompletion widgets:

class OrderModelForm(autocomplete_light.ModelForm):
    class Meta:
        model = Order

Note that the first Autocomplete class registered for a model becomes the default Autocomplete for that model. If you have registered several Autocomplete classes for a given model, you probably want to use a different Autocomplete class depending on the form using Meta.autocomplete_names:

class OrderModelForm(autocomplete_light.ModelForm):
    class Meta:
        autocomplete_names = {'company': 'PublicCompanyAutocomplete'}
        model = Order

autocomplete_light.ModelForm respects Meta.fields and Meta.exclude. However, you can enable or disable autocomplete_light.ModelForm‘s behaviour in the same fashion with Meta.autocomplete_fields and Meta.autocomplete_exclude:

class OrderModelForm(autocomplete_light.ModelForm):
    class Meta:
        model = Order
        # only enable autocompletes on 'person' and 'product' fields
        autocomplete_fields = ('person', 'product')

class PersonModelForm(autocomplete_light.ModelForm):
    class Meta:
        model = Order
        # do not make 'category' an autocomplete field
        autocomplete_exclude = ('category',)

Also, it will automatically enable autocompletes on generic foreign keys and generic many to many relations if you have at least one generic Autocomplete class register (typically an AutocompleteGenericBase).

For more documentation, continue reading the reference documentation.