Usage GuideΒΆ

django_tomselect provides form fields and widgets to integrate Tom Select into your Django projects, enabling dynamic and customizable <select> elements with advanced features like autocomplete, tagging, and search.

Most of the code samples throughout this guide are based on the example app provided with the package. You can find the complete example app in the example_project/example/ directory of the repository.

This guide is split into the following sections:

  • Installation - install the package and wire up the middleware, context processor, and static assets.

  • Quick Start - a complete end-to-end example, from form to view to URLs to template.

  • Core Components - the autocompletes, form fields, and widgets that make up the package.

  • Configuration - the TomSelectConfig object, plugins, and global vs. field-level settings.

  • Working with Models - autocomplete views, queryset filtering, related fields, and search.

  • Working with Forms - integrating fields into forms and ModelForms, initial values, and validation.

  • Advanced Features - dependent/chained fields, exclusions, pagination, and custom search.

  • Customization - styling, custom templates, plugin configuration, and dropdown layouts.

  • Security Considerations - permissions, authorization hooks, caching, and CSP nonce support.