Core Components

django_tomselect is built around a few key components that work together to provide a seamless autocomplete and selection experience in your Django forms. Understanding these components will help you configure and customize the behavior of Tom Select in your application.

Autocompletes

Autocompletes are server-side views that respond to requests from the Tom Select widget. They provide the data-often filtered or searched by the user’s query-that populates the dropdown. Implementing an autocomplete view is crucial for any dynamic search functionality.

AutocompleteModelView

• Purpose: Serves as the primary autocomplete endpoint for model-based data.

• Typical Use Case: When you want to provide a list of model instances (e.g., Magazine objects) to a Tom Select widget, allowing the user to search by name and select one or more items.

• Key Features:

  • Configurable search_lookups to filter data (e.g., name__icontains).

  • Supports pagination, ordering, and filtering by additional parameters.

  • Integrates with Django’s authentication and permission system.

  • Can be subclassed to customize search logic (search(), get_queryset()), filtering (apply_filters()), and result formatting (prepare_results()).

AutocompleteIterablesView

• Purpose: Provides autocomplete data for simple iterables (lists, tuples, or Django choices), rather than model querysets.

• Typical Use Case: When selecting from a static list of values (e.g., a list of countries) without hitting the database.

• Key Features:

  • Offers search capabilities over a static set of values.

  • Pagination and incremental loading for large sets of options.

  • Simpler than AutocompleteModelView, since no ORM queries are involved.

Note

Could you manually add Tom Select to your project and supply iterables as context to the template? Absolutely. But django_tomselect standardizes the process, providing a consistent API, integration with Django forms, and advanced features like filtering and server-side pagination for large datasets.

Form Fields

Form fields integrate django_tomselect widgets into Django’s form system, making it easy to replace traditional ModelChoiceField or ModelMultipleChoiceField fields with Tom Select-enabled versions.

• TomSelectModelChoiceField:

  • Single-select field, wrapping a ModelChoiceField.

  • Ideal when the user must pick exactly one model instance.

• TomSelectModelMultipleChoiceField:

  • Multi-select field, wrapping a ModelMultipleChoiceField.

  • Enables the user to select multiple model instances.

• TomSelectChoiceField:

  • Single-select field for static choices (e.g., tuples, lists, or Django choices).

  • Similar to TomSelectModelChoiceField, but for non-model data.

• TomSelectMultipleChoiceField:

  • Multi-select field for static choices.

  • Similar to TomSelectModelMultipleChoiceField, but for non-model data.

Key Features:

• Each field type automatically binds to a corresponding Tom Select widget.

• Configurations (e.g., url, placeholder) are provided through TomSelectConfig. Note that search_lookups is not a TomSelectConfig option; it is an attribute set on the AutocompleteModelView that defines which model fields the server-side search filters against.

• Behaves like a standard Django model field, making it easy to integrate into ModelForms.

• Ensures validation and data integrity: the chosen options must exist in the referenced queryset.

Widgets

Widgets handle the front-end presentation and behavior of the fields. They render the <select> element, attach the appropriate JavaScript initialization code, and integrate with the autocomplete views.

• TomSelectModelWidget:

  • For single-select fields.

  • Renders as a Tom Select-enhanced <select> field, loading data from a specified autocomplete endpoint.

• TomSelectModelMultipleWidget:

  • For multi-select fields.

  • Similar to TomSelectModelWidget, but allows multiple item selection.

• TomSelectIterablesWidget:

  • For static choice fields (iterables, enums, tuples, ranges).

  • Renders a Tom Select-enhanced <select> field for static choices.

• TomSelectIterablesMultipleWidget:

  • For static multiple choice fields.

  • Similar to TomSelectIterablesWidget, but for multiple selections.

Key Features:

• Customize look, feel, and behavior through TomSelectConfig and widget attributes.

• Seamless integration with autocomplete views: the widget automatically fetches data based on user input.

• Supports advanced features like dependent/chained fields, custom templates, plugin configurations, and HTMX integration.

• Works well with different CSS frameworks (e.g., Bootstrap) for styling, as well as custom templates for full UI control.

Token-based (Composite) Components

For advanced search interfaces, django_tomselect provides a token-based workflow in which a single input can search across multiple entities at once. The user types a query made up of operator-scoped tokens (for example, author:42 category:5 free text).

• CompositeAutocompleteView:

  • Multiplexes multiple autocomplete views into a single token-aware endpoint.

  • Exposes routes to list the registered operators, delegate value lookups to the appropriate bound autocomplete view per operator, and batch-resolve labels for given operator and id pairs.

  • Enables the token-based (composite) autocomplete workflow where one input searches across several entities.

• TomSelectTokenWidget:

  • A token-style input that multiplexes multiple autocomplete views.

  • Renders a single text input whose serialized value is a canonical token string (e.g., author:42 category:5 free text).

  • Configured by a URL name pointing at the composite endpoint (class references are not accepted, since the browser plugin needs a URL to call).

• TomSelectTokenField:

  • A CharField that parses and validates a token-style query string.

  • Its clean() method parses the input against the bound CompositeAutocompleteView using parse_query(), raising ValidationError for unknown operators, count overflows, or forbidden free text.

  • Enforces per-operator max_count/min_count constraints from the operator registry.