Quick Start¶

This section guides you through a simple, end-to-end example of integrating django_tomselect into your Django project. By the end, you’ll have a functioning autocomplete-enabled select field that dynamically fetches options from the server as the user types.

Basic Form Implementation¶

The simplest approach is to add a TomSelectModelChoiceField to a basic form. This field uses a TomSelectConfig that specifies where to fetch data from and how to display it.

from django import forms
from django_tomselect import TomSelectConfig, TomSelectModelChoiceField

class SimpleForm(forms.Form):
    magazine = TomSelectModelChoiceField(
        config=TomSelectConfig(
            url="autocomplete-magazine",  # Name of the URL pattern for your autocomplete view
            value_field="id",             # Field returned as the <option> value
            label_field="name",           # Field displayed as the <option> label
            placeholder="Select a magazine...",
            preload="focus",              # Load options when the field is focused, instead of waiting for a query
            highlight=True                # Highlight query matches in the dropdown
        )
    )

In this snippet:

The url parameter points to an autocomplete endpoint you’ll define.
The value_field and label_field specify which model fields represent the option’s value and label.
Additional parameters like placeholder and highlight enhance the user experience.

ModelForm Integration¶

Integrating with a Django ModelForm is straightforward-just replace a standard model field with a TomSelectModelChoiceField. Suppose you have an Article model that references a Magazine model via a ForeignKey:

from django import forms
from django_tomselect import TomSelectConfig, TomSelectModelChoiceField
from .models import Article

class ArticleForm(forms.ModelForm):
    magazine = TomSelectModelChoiceField(
        config=TomSelectConfig(
            url="autocomplete-magazine",
            value_field="id",
            label_field="name",
            placeholder="Select a magazine...",
            minimum_query_length=2,  # Only start searching after 2 chars
            preload="focus"
        )
    )

    class Meta:
        model = Article
        fields = ["title", "magazine"]

This form field will automatically integrate with Tom Select, providing an enhanced dropdown with autocomplete and search capabilities.

Setting Up the Views¶

Configure the Autocomplete View¶

Create a subclass of AutocompleteModelView to provide data to the widget. For example, if your Magazine model has a name field:

from django_tomselect.autocompletes import AutocompleteModelView
from .models import Magazine

class MagazineAutocompleteView(AutocompleteModelView):
    model = Magazine
    search_lookups = ["name__icontains"]  # Fields to search against
    ordering = ["name"]
    page_size = 20

This view will respond to requests from the widget, returning JSON data for matching magazines.

Use the Form in a View¶

Create a simple view that handles displaying and processing the ArticleForm:

from django.shortcuts import redirect
from django.template.response import TemplateResponse
from .forms import ArticleForm

def article_create_view(request):
    template = "article_form.html"
    context = {}

    form = ArticleForm(request.POST or None)
    if request.method == "POST" and form.is_valid():
        form.save()
        return redirect("article-list")  # Adjust the redirect as needed

    context["form"] = form
    return TemplateResponse(request, template, context)

Add URL Patterns¶

from django.urls import path
from .views import article_create_view, MagazineAutocompleteView

urlpatterns = [
    path("article/create/", article_create_view, name="article-create"),
    path("autocomplete/magazine/", MagazineAutocompleteView.as_view(), name="autocomplete-magazine"),
]

Template Setup¶

Include the form’s media assets in your template to ensure that Tom Select CSS and JS are properly loaded. Your form template might look like this:

<!DOCTYPE html>
<html lang="en">
<head>
    <!-- Include form's media -->
    {{ form.media }}
</head>
<body>
    <form method="post">
        {% csrf_token %}
        {{ form.as_p }}
        <button type="submit">Submit</button>
    </form>
</body>
</html>

That’s it! With this setup, you have a working autocomplete-enabled select field that:

Dynamically fetches results as the user types
Integrates seamlessly with Django ModelForms
Supports search filtering, pagination, and keyboard navigation out-of-the-box