Django Multiple Select Field

1.0.1 · active · verified Mon Apr 13

django-multiselectfield provides new model and form fields for Django, allowing users to select multiple options from a predefined list. The selected values are stored in the database as a CharField containing comma-separated values. The current version is 1.0.1, and the project has an irregular release cadence, with a significant 1.0.0 release in June 2025 that introduced breaking changes.

Warnings

breaking Version 1.0.0 removed `MSFList` and `MSFFlatchoices`. These classes were intended for `admin.list_display` but never functioned correctly.
Fix: Remove any references to `MSFList` or `MSFFlatchoices` from your code. If you were using them for `list_display`, consider using `get_FOO_display` method on your model or a custom admin method.
breaking As of version 1.0.0, integer choices are no longer supported. `MultiSelectField` inherits from `CharField`, and it's impossible to reliably distinguish between integer `1` and string `'1'` upon retrieval from the database.
Fix: Ensure all choices provided to `MultiSelectField` are string-based. For example, use `(('1', 'Item 1'), ('2', 'Item 2'))` instead of `((1, 'Item 1'), (2, 'Item 2'))`.
gotcha Adding a `MultiSelectField` directly to `list_display` in Django admin might not render as expected (e.g., showing a raw comma-separated string).
Fix: Use a custom method on your `ModelAdmin` or the `get_FOO_display` method on your model to format the output for `list_display`. Example: `list_display = ('get_my_field_display',)` in `ModelAdmin` where `get_my_field_display` is a method on the model.
gotcha The `SortMultiSelectField` (introduced in v1.0.0) requires jQuery and jQuery UI to function correctly in the browser. These libraries are typically included in the Django admin interface.
Fix: Ensure jQuery and jQuery UI are loaded in your templates when using `SortMultiSelectField` outside of the default Django admin forms. In the admin, you might need to explicitly include them in your `ModelAdmin`'s `form` definition or `change_form.html`.
gotcha As a `CharField` subclass, `MultiSelectField` stores values as comma-separated strings. Avoid setting `null=True` on `CharField`s in Django, as it's generally recommended to use `blank=True` and `default=''` for string-based fields.
Fix: Use `blank=True, default=''` instead of `null=True` for `MultiSelectField` if the field is optional.

Install

pip install django-multiselectfield Install stable version

Imports

MultiSelectField
```
from multiselectfield import MultiSelectField
```
Used for creating model fields that allow multiple selections.
SortMultiSelectField
```
from multiselectfield import SortMultiSelectField
```
Introduced in v1.0.0 for sortable multi-select fields; requires jQuery and jQuery UI.

Quickstart

To use `MultiSelectField`, define your choices as a tuple of tuples. Add `multiselectfield` to your `INSTALLED_APPS` and then define a model field using `MultiSelectField`. Remember to run `makemigrations` and `migrate`.

from django.db import models
from multiselectfield import MultiSelectField

# In your settings.py, ensure 'multiselectfield' is in INSTALLED_APPS
# INSTALLED_APPS = [
#     # ...
#     'multiselectfield',
#     # ...
# ]

MY_CHOICES = (
    ('item_key1', 'Item title 1.1'),
    ('item_key2', 'Item title 1.2'),
    ('item_key3', 'Item title 1.3'),
    ('item_key4', 'Item title 1.4'),
    ('item_key5', 'Item title 1.5')
)

class MyModel(models.Model):
    my_field = MultiSelectField(choices=MY_CHOICES, default=['item_key1', 'item_key5'])
    my_field_with_limits = MultiSelectField(
        choices=MY_CHOICES,
        min_choices=2,
        max_choices=3,
        max_length=100 # Adjust max_length based on expected comma-separated string length
    )

    def __str__(self):
        return f"{self.my_field} - {self.my_field_with_limits}"

# After defining your model, run:
# python manage.py makemigrations
# python manage.py migrate

view raw JSON →