Template Tags

The django_tomselect template tags provide utilities for including TomSelect’s CSS and JavaScript assets in your templates.

Usage

First, load the template tags in your template:

{% load django_tomselect %}

Template tags for including TomSelect CSS and JS when the form is unavailable.

Usage:

{% load django_tomselect %}

<!– Include CSS and JS with default CSS framework –> {% tomselect_media %}

<!– Include CSS and JS with specific CSS framework –> {% tomselect_media css_framework=”bootstrap5” %}

<!– Or only CSS with specific framework –> {% tomselect_media_css css_framework=”bootstrap4” %}

<!– Or only JS –> {% tomselect_media_js %}

django_tomselect.templatetags.django_tomselect.get_widget_with_config(css_framework=None, use_minified=None)[source]

Get a TomSelectIterablesWidget instance with the specified configuration.

Creates a new widget instance and configures it with the specified CSS framework and minification preference if provided.

Parameters:

  • css_framework (str | None) – Optional name of the CSS framework to use

  • use_minified (bool | None) – Optional flag to use minified CSS/JS files

Returns:

A configured TomSelectIterablesWidget instance

Return type:

TomSelectIterablesWidget

Render CSS links from a dictionary of media types and paths.

Takes a dictionary mapping media types to lists of CSS file paths and renders them as HTML link tags.

Parameters:

css_dict (dict) – Dictionary mapping media types to lists of CSS file paths

Returns:

HTML string containing link tags for the CSS files

Return type:

str

django_tomselect.templatetags.django_tomselect.render_js_scripts(js_list)[source]

Render JS script tags from a list of paths.

Takes a list of JavaScript file paths and renders them as HTML script tags.

Parameters:

js_list (list) – List of JavaScript file paths

Returns:

HTML string containing script tags for the JavaScript files

Return type:

str

django_tomselect.templatetags.django_tomselect.to_static_url(path)[source]

Convert a path to a static URL.

Takes a path and returns either the absolute URL if it’s already a complete URL, or converts it to a static URL using Django’s static function.

Parameters:

path (str) – The path to convert to a static URL

Returns:

The static URL for the given path

Return type:

str

django_tomselect.templatetags.django_tomselect.tomselect_media(css_framework=None, use_minified=None)[source]

Return all CSS and JS tags for the TomSelectIterablesWidget.

Creates the necessary HTML tags to include TomSelect CSS and JavaScript files in a template.

Parameters:

  • css_framework (str | None) – Optional name of the CSS framework to use

  • use_minified (bool | None) – Optional flag to use minified CSS/JS files

Returns:

Safe HTML string containing all required CSS and JS tags

Return type:

str

django_tomselect.templatetags.django_tomselect.tomselect_media_css(css_framework=None, use_minified=None)[source]

Return only CSS tags for the TomSelectIterablesWidget.

Creates the necessary HTML tags to include only TomSelect CSS files in a template.

Parameters:

  • css_framework (str | None) – Optional name of the CSS framework to use

  • use_minified (bool | None) – Optional flag to use minified CSS files

Returns:

Safe HTML string containing all required CSS tags

Return type:

str

django_tomselect.templatetags.django_tomselect.tomselect_media_js(use_minified=None)[source]

Return only JS tags for the TomSelectIterablesWidget.

Creates the necessary HTML tags to include only TomSelect JavaScript files in a template.

Parameters:

use_minified (bool | None) – Optional flag to use minified JS files

Returns:

Safe HTML string containing all required JS tags

Return type:

str

Media Tags

tomselect_media

Includes all required CSS and JavaScript files for TomSelect.

{% tomselect_media %}

With custom CSS framework:

{% tomselect_media css_framework="bootstrap5" %}

With minification control:

{% tomselect_media use_minified=True %}

This tag outputs:

<!-- With default framework -->
<link href="/static/django_tomselect/vendor/tom-select/css/tom-select.default.min.css" rel="stylesheet" media="all">
<link href="/static/django_tomselect/css/django-tomselect.css" rel="stylesheet" media="all">
<script src="/static/django_tomselect/js/django-tomselect.min.js"></script>

<!-- With Bootstrap 5 -->
<link href="/static/django_tomselect/vendor/tom-select/css/tom-select.bootstrap5.min.css" rel="stylesheet" media="all">
<link href="/static/django_tomselect/css/django-tomselect.css" rel="stylesheet" media="all">
<script src="/static/django_tomselect/js/django-tomselect.min.js"></script>

tomselect_media_css

Includes only the CSS files for TomSelect.

{% tomselect_media_css %}

With custom CSS framework:

{% tomselect_media_css css_framework="bootstrap4" %}

This tag outputs:

<link href="/static/django_tomselect/vendor/tom-select/css/tom-select.bootstrap4.min.css" rel="stylesheet" media="all">
<link href="/static/django_tomselect/css/django-tomselect.css" rel="stylesheet" media="all">

tomselect_media_js

Includes only the JavaScript files for TomSelect.

{% tomselect_media_js %}

With minification control:

{% tomselect_media_js use_minified=False %}

This tag outputs:

<script src="/static/django_tomselect/js/django-tomselect.js"></script>

Common Usage Patterns

Base Template

Include the assets in your base template:

{% load django_tomselect %}
<!DOCTYPE html>
<html>
<head>
    <title>{% block title %}{% endblock %}</title>
    {% tomselect_media_css css_framework="bootstrap5" %}
</head>
<body>
    {% block content %}{% endblock %}

    {% tomselect_media_js %}
</body>
</html>

CSS Framework Options

The template tags support the following CSS frameworks:

  • default: Tom Select’s default styling

  • bootstrap4: Bootstrap 4 compatible styling

  • bootstrap5: Bootstrap 5 compatible styling

{# Default styling #}
{% tomselect_media %}

{# Bootstrap 4 #}
{% tomselect_media css_framework="bootstrap4" %}

{# Bootstrap 5 #}
{% tomselect_media css_framework="bootstrap5" %}

!!! note “Static file ordering for Bootstrap themes” When using bootstrap4 or bootstrap5, load the corresponding Bootstrap CSS before {% tomselect_media %} in your template. The Bootstrap 5 theme in particular relies on CSS custom properties (--bs-border-color, --bs-body-bg, etc.) defined by Bootstrap. Built-in fallback values ensure basic rendering even without Bootstrap loaded, but including Bootstrap first gives the most accurate styling.

Development vs Production

In development:

{% tomselect_media use_minified=False %}

In production:

{% tomselect_media use_minified=True %}

Or use Django’s settings:

# settings.py
TOMSELECT = {
    'DEFAULT_USE_MINIFIED': not DEBUG
}