Django TomSelect
A powerful, lightweight Django package for dynamic select inputs with autocomplete, tagging, and more.
Django TomSelect integrates Tom Select into your Django projects, providing beautiful and intuitive select inputs with features like:
-
Live Search & Autocomplete
- Real-time filtering and highlighting as you type
- Server-side search with customizable lookups
- Automatic pagination for large datasets
- Customizable minimum query length
-
Rich UI Options
- Single and multiple selection modes
- Tabular display with custom columns
- Bootstrap 4/5 theming support
- Clear/remove buttons
- Dropdown headers & footers
- Checkbox options
- Customizable templates
Quick Start
- Install the package:
pip install django-tomselect
- Update settings.py:
INSTALLED_APPS = [
...
"django_tomselect"
]
MIDDLEWARE = [
...
"django_tomselect.middleware.TomSelectMiddleware",
...
]
TEMPLATES = [
{
"OPTIONS": {
"context_processors": [
...
"django_tomselect.context_processors.tomselect",
...
],
},
},
]
- Create an autocomplete view:
from django_tomselect.autocompletes import AutocompleteModelView
class PersonAutocompleteView(AutocompleteModelView):
model = Person
search_lookups = ["full_name__icontains"]
value_fields = ["id","full_name"]
- Add URL pattern:
urlpatterns = [
path("person-autocomplete/", PersonAutocompleteView.as_view(), name="person_autocomplete"),
]
- Use in your forms:
from django_tomselect.forms import TomSelectModelChoiceField, TomSelectConfig
class MyForm(forms.Form):
person = TomSelectModelChoiceField(
config = TomSelectConfig(
url="person_autocomplete",
value_field="id",
label_field="full_name",
)
)
- Include in your template:
{{ form.media }} {# Adds the required CSS/JS #}
{{ form }}
Other Features
Advanced Filtering
- Dependent/chained select fields
- Field exclusion support
- Custom search implementations
- Hooks for overriding functionality
Flexible Configuration
- Support for Tom Select Plugins
- Global settings and per-form-field configuration
- Override any template
Security
- Built-in permission handling
- including django auth, custom auth, object perms
Internationalization
- Translation support
- Customizable messages
Example Project
To see Django TomSelect in action, check out the Example Project. It demonstrates a variety of use cases, with 15 different implementations from basic atocompletion to advanced applications, showing how to use django-tomselect's autocomplete fields in a Django project.
Each of the examples is described in the Example Project docs.
Here are a few screenshots from the example project:
Documentation
Contributing
Contributions are welcome! Check out our Contributor Guide to get started.
License
This project is licensed under the MIT License - see the License file for details.
Acknowledgments
This package builds on the excellent work of Philip Becker in mizdb-tomselect, with a focus on generalization, Django templates, translations, and customization.
Release files for django-tomselect 2026.6.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| django_tomselect-2026.6.2.tar.gz | 285.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| django_tomselect-2026.6.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 608.2 kB
Release files / django_tomselect-2026.6.2.tar.gz
| Download URL | django_tomselect-2026.6.2.tar.gz |
|---|---|
| Size | 285.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
584da0f81889da263bf1498484f414b022ae6d4df968bd44169161084084ff1a
|
|
BLAKE2b-256 checksum How to use checksums |
bba63780a9bc35ca62897bc720a01f575d47b036d8ecc5aea63615479600d760
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.3 {"installer":{"name":"uv","version":"0.11.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / django_tomselect-2026.6.2-py3-none-any.whl
| Download URL | django_tomselect-2026.6.2-py3-none-any.whl |
|---|---|
| Size | 323.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
726f713a203015319045ecd09f4935394e4040357ba52c9bbfaaaf74ff96c501
|
|
BLAKE2b-256 checksum How to use checksums |
cfd6e0b85e7432eaea047e83d475680d47824a6e8215c087df5b2a989904ddbb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.3 {"installer":{"name":"uv","version":"0.11.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
