# Django TomSelect
A powerful, lightweight Django package for dynamic select inputs with autocomplete, tagging, and more.
[](https://badge.fury.io/py/django-tomselect)
[](https://github.com/OmenApps/django-tomselect/blob/main/LICENSE)
Django TomSelect integrates [Tom Select](https://tom-select.js.org/) 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
1. **Install the package:**
```bash
pip install django-tomselect
```
2. **Update settings.py:**
```python
INSTALLED_APPS = [
...
"django_tomselect"
]
MIDDLEWARE = [
...
"django_tomselect.middleware.TomSelectMiddleware",
...
]
TEMPLATES = [
{
"OPTIONS": {
"context_processors": [
...
"django_tomselect.context_processors.tomselect",
...
],
},
},
]
```
3. **Create an autocomplete view:**
```python
from django_tomselect.autocompletes import AutocompleteModelView
class PersonAutocompleteView(AutocompleteModelView):
model = Person
search_lookups = ["full_name__icontains"]
```
4. **Add URL pattern:**
```python
urlpatterns = [
path("person-autocomplete/", PersonAutocompleteView.as_view(), name="person_autocomplete"),
]
```
5. **Use in your forms:**
```python
from django_tomselect.forms import TomSelectModelChoiceField
class MyForm(forms.Form):
person = TomSelectModelChoiceField(
url="person_autocomplete",
value_field="id",
label_field="full_name",
)
```
6. **Include in your template:**
```html
{{ 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](https://tom-select.js.org/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
## Documentation
- [Complete Usage Guide](https://django-tomselect.readthedocs.io/en/latest/usage/)
- [Configuration Reference](https://django-tomselect.readthedocs.io/en/latest/api/config/)
- [API Reference](https://django-tomselect.readthedocs.io/en/latest/api/)
## Contributing
Contributions are welcome! Check out our [Contributor Guide](https://github.com/OmenApps/django-tomselect/blob/main/CONTRIBUTING.md) to get started.
## License
This project is licensed under the MIT License - see the [License](https://github.com/OmenApps/django-tomselect/blob/main/LICENSE) file for details.
## Acknowledgments
This package builds on the excellent work of [Philip Becker](https://pypi.org/user/actionb/) in [mizdb-tomselect](https://www.pypi.org/project/mizdb-tomselect/), with a focus on generalization, Django templates, translations, and customization.
Raw data
{
"_id": null,
"home_page": null,
"name": "django-tomselect",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "django, autocomplete, tomselect, widget, forms, views, select, multiselect",
"author": null,
"author_email": "Jack Linke <jacklinke@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/79/de/0dc75dd1cec9ac8bc29b1939f7b0e39ef54cda3f454a38bef48833b643cd/django_tomselect-2024.12.2.tar.gz",
"platform": null,
"description": "\n\n# Django TomSelect\n\nA powerful, lightweight Django package for dynamic select inputs with autocomplete, tagging, and more.\n\n[](https://badge.fury.io/py/django-tomselect)\n[](https://github.com/OmenApps/django-tomselect/blob/main/LICENSE)\n\nDjango TomSelect integrates [Tom Select](https://tom-select.js.org/) into your Django projects, providing beautiful and intuitive select inputs with features like:\n\n- **Live Search & Autocomplete**\n - Real-time filtering and highlighting as you type\n - Server-side search with customizable lookups\n - Automatic pagination for large datasets\n\t- Customizable minimum query length\n\n- **Rich UI Options**\n - Single and multiple selection modes\n - Tabular display with custom columns\n - Bootstrap 4/5 theming support\n\t- Clear/remove buttons\n\t- Dropdown headers & footers\n\t- Checkbox options\n - Customizable templates\n\n\n\n\n## Quick Start\n\n1. **Install the package:**\n```bash\npip install django-tomselect\n```\n\n2. **Update settings.py:**\n```python\nINSTALLED_APPS = [\n ...\n \"django_tomselect\"\n]\n\nMIDDLEWARE = [\n ...\n \"django_tomselect.middleware.TomSelectMiddleware\",\n ...\n]\n\nTEMPLATES = [\n {\n \"OPTIONS\": {\n \"context_processors\": [\n ...\n \"django_tomselect.context_processors.tomselect\",\n ...\n ],\n },\n },\n]\n```\n\n3. **Create an autocomplete view:**\n```python\nfrom django_tomselect.autocompletes import AutocompleteModelView\n\nclass PersonAutocompleteView(AutocompleteModelView):\n model = Person\n search_lookups = [\"full_name__icontains\"]\n```\n\n4. **Add URL pattern:**\n```python\nurlpatterns = [\n path(\"person-autocomplete/\", PersonAutocompleteView.as_view(), name=\"person_autocomplete\"),\n]\n```\n\n5. **Use in your forms:**\n```python\nfrom django_tomselect.forms import TomSelectModelChoiceField\n\nclass MyForm(forms.Form):\n person = TomSelectModelChoiceField(\n url=\"person_autocomplete\",\n value_field=\"id\",\n label_field=\"full_name\",\n )\n```\n\n6. **Include in your template:**\n```html\n{{ form.media }} {# Adds the required CSS/JS #}\n\n{{ form }}\n```\n\n## Other Features\n\n### Advanced Filtering\n- Dependent/chained select fields\n- Field exclusion support\n- Custom search implementations\n- Hooks for overriding functionality\n\n### Flexible Configuration\n- Support for [Tom Select Plugins](https://tom-select.js.org/plugins/)\n- Global settings and per-form-field configuration\n- Override any template\n\n### Security\n- Built-in permission handling\n\t- including django auth, custom auth, object perms\n\n### Internationalization\n- Translation support\n- Customizable messages\n\n## Documentation\n\n- [Complete Usage Guide](https://django-tomselect.readthedocs.io/en/latest/usage/)\n- [Configuration Reference](https://django-tomselect.readthedocs.io/en/latest/api/config/)\n- [API Reference](https://django-tomselect.readthedocs.io/en/latest/api/)\n\n## Contributing\n\nContributions are welcome! Check out our [Contributor Guide](https://github.com/OmenApps/django-tomselect/blob/main/CONTRIBUTING.md) to get started.\n\n## License\n\nThis project is licensed under the MIT License - see the [License](https://github.com/OmenApps/django-tomselect/blob/main/LICENSE) file for details.\n\n## Acknowledgments\n\nThis package builds on the excellent work of [Philip Becker](https://pypi.org/user/actionb/) in [mizdb-tomselect](https://www.pypi.org/project/mizdb-tomselect/), with a focus on generalization, Django templates, translations, and customization.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Django autocomplete widgets and views using Tom Select",
"version": "2024.12.2",
"project_urls": {
"Changelog": "https://github.com/OmenApps/django-tomselect/releases",
"Documentation": "https://django-tomselect.readthedocs.io/en/latest/",
"Issues": "https://github.com/OmenApps/django-tomselect/issues",
"Source": "https://github.com/OmenApps/django-tomselect"
},
"split_keywords": [
"django",
" autocomplete",
" tomselect",
" widget",
" forms",
" views",
" select",
" multiselect"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a3fc7c69483a01b24a529e8ba056f9c7b6b18b753886b057fd707d3be548e993",
"md5": "5931baa225f02b7b11ba7f0b09710e7f",
"sha256": "ca0546f1ca870c40f00ebf68adb4ec6a0a8f611592af274b6a5a2fc05e7aac32"
},
"downloads": -1,
"filename": "django_tomselect-2024.12.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5931baa225f02b7b11ba7f0b09710e7f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 215275,
"upload_time": "2024-12-16T04:24:11",
"upload_time_iso_8601": "2024-12-16T04:24:11.184080Z",
"url": "https://files.pythonhosted.org/packages/a3/fc/7c69483a01b24a529e8ba056f9c7b6b18b753886b057fd707d3be548e993/django_tomselect-2024.12.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "79de0dc75dd1cec9ac8bc29b1939f7b0e39ef54cda3f454a38bef48833b643cd",
"md5": "6858b9f3dad9c73d6ac5b7353d769165",
"sha256": "8610ef0d85066937996e3826ac955379740db6fe371dc688c00f64117d904d1f"
},
"downloads": -1,
"filename": "django_tomselect-2024.12.2.tar.gz",
"has_sig": false,
"md5_digest": "6858b9f3dad9c73d6ac5b7353d769165",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 187593,
"upload_time": "2024-12-16T04:24:14",
"upload_time_iso_8601": "2024-12-16T04:24:14.031874Z",
"url": "https://files.pythonhosted.org/packages/79/de/0dc75dd1cec9ac8bc29b1939f7b0e39ef54cda3f454a38bef48833b643cd/django_tomselect-2024.12.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-16 04:24:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "OmenApps",
"github_project": "django-tomselect",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "asgiref",
"specs": [
[
"==",
"3.8.1"
]
]
},
{
"name": "django",
"specs": [
[
"==",
"5.1.2"
]
]
},
{
"name": "django-htmx",
"specs": [
[
"==",
"1.21.0"
]
]
},
{
"name": "iniconfig",
"specs": [
[
"==",
"2.0.0"
]
]
},
{
"name": "packaging",
"specs": [
[
"==",
"24.2"
]
]
},
{
"name": "pluggy",
"specs": [
[
"==",
"1.5.0"
]
]
},
{
"name": "pytest",
"specs": [
[
"==",
"8.3.4"
]
]
},
{
"name": "pytest-asyncio",
"specs": [
[
"==",
"0.25.0"
]
]
},
{
"name": "sqlparse",
"specs": [
[
"==",
"0.5.1"
]
]
}
],
"lcname": "django-tomselect"
}
JSON
